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GEHING STARTED 



Ac various placee in the texE you will see the special eytnbal 



If you don't already know how to start up the Apple Pascal Operatltje 
System for use with the Apple Pascal langugge, please read Appendix D if 
you have one diskette drive, or Appendix E If you have two or more 
diskEtte drives- Each of these Appendices le a tutorial session, 
covering system startup, diskette Irit Jalliotion, diskette copying, and 
a detsorifi tratlon of Apple Pascal progfanii&ing ■ 



SCOPE OF THIS DOCUMENT 



This document covers the features of the Apple Faacal programming 
language that are different from the "Standard Pascal'^ language defined 
by Jensen and Wlrth in the Pascal User Man ua 1 and Rej>o r t (Sprloger- 

Verlag, New York, 197S), This incUidea the differences Introduced in 
UCSD PsBcal, find also special eiitensione of UCSD Pascal for the Apple 
computer* 

The Apple Pascal system facilities such as the Editor, the Linker, etc* 
are covered tti the Apple Pascal Operating System Reference Hflnual, 
These facilities are useful in various applications besides Apple Pascal 
progranming; they are discussed here only as they relate specifically to 
Apple Pascal programa* 

HOW TO USE THiS DOCUMENT 

Ta use this document you must either tiave a thorough knowledge of 
Standard or UCSP Pascal, or use some book or manual that fully describes 
Standard or I'CSD Pascal. This 1b » reference i:ianual, designed to give 
you the facts without very much etnphaels on teaching you Pascal- 

You should also have the Apple Pascal Cperatiiig System Reference Manual, 
uhlcb gives complete information on the various systen: facilities that 
support Che creation and development of Apple Pascal programs- 

One aspect of the Apple Pascal Operating System is covered in this 
raanualj the procedures for starting up the syHCem when your purpose Is 
to work vlth Applf Pascal programs. Appenillcee D a,nd E describe these 
procedures . 
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which indicates a feature that you need to be cautious about. Another 
special symbol is 



! ,-. % 



which Indicates a particularly useful piece of Information (usually 
something that is not obvious). 



ORGANIZATION / 

Chapters 2 and 3 cover the large differencea in Apple Pascal that will 
have the most iffitoedlate progcatnming Impact: the differences in 
predefined types, procedures, and functlooa, especially the prociedures 
for input and output* 

Chapter 4 covers the compiler operation and the compiler optlonSj which 
are powerful and important- Further details on cou^ller operation can 
be found lo the Apple Pascal Operating System Reference Manual* 

Chaptei: S covera techniques for breaking a prograti into separate pieces 
which can be linked together- These techniquea are another major area 

of difference but are not needed for small programs- 

Chapter 6 gives the remaining differences in the language, which are of 
minor impact for most programs- 
Chapter 7 covers the ei^tremely powerful library options of Apple Pascal, 
including the Turtlegraphics package- 
Appendix A presents a fully annotated program that uaes graphics^ and 
alao describes the detaonatratlon programs supplied with Apple Pascal- 
Appendix B contains various tables relating to the Apple Pascal Language 
and the system- 



Z 3 Appendix C gives some technical details on textflle 1/0 operations- 
Appendices D and E cover system startup and essential operating 
procedures for use with the Apple Pascal language* 

Appendix F is a complete set of syntax diagrams for Che Apple Pascal 
language - 
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NOTATION USED [N THIS MANUAL 

In syntax descclptlons^ the following convention ia uBqd: 

- Squace braclcete [] are used to enclose anything that may 
legally be ocaltted from Che syntax. 



DIFFERENCES BETWEEN APPLE 
AND STANDARD MSCAL 



The najor differeneee are suranarlzed below; see Chapter & for the minor 
ones* 



PREDEFINED VARIABLE TYPES 

- A new variable Eype^ STRtNG, aupported by a set of new 
built-in procedures and functlona* See Chapters 2 
and 3* 

- k flew file type, INTERACTIVE, supported by tlie extended file 
1/0 procedurea and functions- See Chapters 2 and 3* 

- Minor restrictions en SET typea. 

- Hlnor differences in the treatment of PACKED variables . 
Automatic PACK and UNPACK operations ^ with eliadnatlDn of the 

PACK and UNPACK procedures of Standard Pascal. See 
Chapter 2. 

- An extension of the INTEGER type called LOSG TIJTEGER. A LONG 
INTEGER Is a value represented by up Co 36 binary-coded 
declnal (BCD) digits. See Chapter 2. 



BUILT-IN PROCEDURES AND FUNCTIONS 

these are the procedures and functions that are part of the Apple Pascal 
language Itself, as opposed to epecial-purpoae functions Implemented In 
the syatem library. Built-in procedures and functions are called 
"built-ins" for short. 



New bullc-lna supporting STRING variables, 
and 3< 



See Chapters 2 



Extended definitions of the built-lne for file l/t>, aupportlng 
INTERACTIVE fllea* See Chapters 2 and 3. 
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- A set of new byte^^rlented bullf-inB* See Chapter 3. 

- New built-lns called HARK and RELEASE which replace the 
DISPOSE of Standard Pascal. See Chapter 3. 

- Other new built-ins and redefinitions of Standard Pascal 
built-ine . See Chapter 3- 

- The transcendental function^ STN, COS, EXP, ATAN, LN» LOG, and 
SQRT are not buUt-lns In Apple Peecal- They are provided as 
library functions. See Chapter 1 - 



BREAKING PROGRAMS INTO PIECES 

- SEGMENT procedures and functional which reside in memory only 

vhen active. See Chapter 5, 



DNITS, which are separately compiled collections of procedures 
that can be integrated into any lioat progratc via a library 
facility. See Chapter 5- 

EXTKFNAL procedures and functions, which are d&clared In an 
Apple Pascal program but iicplcTnented in aeeeinbly language and 
then integrated Into a host program via the library facility- 
See Chapter 5. 



SPECIAL UNITS FOR THE APPLE 

— These are major fsclllties for the Apple, Impleiaerited aS UNITfi 
in a system library. They include the Turtlegraphtcs package 
for the high-resolution color display of the Apple- See 
Chapter 7. 
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In addillon to the predefined types of Standard Pascal (EEA!^, INTEGER 
CHAR, ARRAY, etcO » Apple Pascal has a STRINC type, an INTERACTIVE file 
typej and 9 LONG IMTECER type* 

Also, the details of certain other predeEined types differ fcota Standard 
PascAl* 



± 



THE STRING TYPE 



Apple Pascal has a new predeclared typcj STRING. The value of a STRING 
variable is a sequence of charactere. Variables of type STRING are 
essentially PACKED ARRAYs OF CHAR that have a dynamically changing 
number of elements (characters). However, the value of a STRING 
variable cannot be assigned tc a PACKED ARRAY OF CHAR, and the value of 
a PACKED ARRAY OF CHAR cannot be assigned to a STRING variable. Strings 
are supported by a set of built-in pTocedures and functionsj see 
Chapter 3* 

The number of characters in a stfing at any netnenE is the len£tb of the 
string. The default maximum length of a STRINC> variable la flfli 
characters, but this can be overridden in the declaration of a STRING 
variable ftip Co the absolute limit o£ 255). To do so, put the desired 
inaximini length In [brackets] after the type identifier STRING, Examples 
of declarations of STRING vatiablea are: 

TITXE^ STRINGj (* defaults Co a TiB3?lmur] length of 3(3 characters *) 

NAME: STRING [30]; f* alloWH the STRING to be a [laxlpiun] of 3^ 

characters*) 

The value of a STRING variable can be altered by aslng an assigniaent 
Btateioent with a string constant or another STRING variable: 



TITLE := 



THIS IS A TITLE 



or 

NAME :- TITLE 

dr hy Tueans of the RJEAD procedure d« described in the next chapter: 

READLN (TITLE) 

or by nieane of the STRING built-lna, also described In the next 
chapter: 

WAME:= C0FY(TITLEjI,3{|) 

Note that a. atring conatant may not contain an end-of-line; the conatant 
must be on a single line in the program- 
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The individual ctiaracters within a STRING are Indexed fron I to the 
LENGTH of the STKlNG. LENGTH is a built-in function which Is described 

in Chapter 3. For exan^le. If TITLE is the nano of a strlngi then 

TITLEEl] 
le 9 reference to the first character of TITLE, and 

TITLE [ LENGTH (TITLE) ] 

is 3 reference to the last character of TITLE* 

A variable of type STRING jaay be compared to any other variable of type 
STRING or to a string constant, regardless of its current dynaralc 
length. The comparison la lexicographical: i.e., one etrlng la "greater 
Chan" another It it would come first in an alphabetic llet of strings. 
The orderinE of the ASCII character set (see Appendix B) is used to 
determiTie this* The following program is a dcmanatration of legal 
comparisons involving variables of type STRING: 

PROGRAM COMPAR£STRIKGS j 
VAR S: STKIWGj 

Tr STRING [^0]; 

BEGIN 

S:- 'SOHETHING'j 

Tr- 'SOMETHING filGCER'; 

IF S - T THEN 

WRITELN( 'Strings do not work very w^U') 
ELSE 

IF S > T THEN 

WRITELN(S,' Is greater than ',T) 

ELSE 

IF S < T THEN 

WRIIELN(S,' Ig less than %T); 
IF S - 'SOMETHING' THEN 

WRITEXN (S, ' equals ' ,S ) j 
IF S > 'SAMETHlNC' THEN 

WRirELN(S,' is greater than SAMETHING'); 
IF S = 'SOMETHING ' THEN 

MRITELNf'BLAWKS D0N"T COtTNT') 
ELSE 

WRITELN ('BLANKS APPEAR TO MAKE A DIFFERENCE'); 
Si^'XXX'; 

T;-'ABCDEF'; 
IF S > T THEN 

WRITKLN{S/ is greater than ',T) 
ELSE 

WRITELN(S,' Is less than ',T) 
ENS, 
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The above program produces the^ followlTig output: 

SOMETKIWC Is less than SOMETHING BIGGER 

5 0MEIH^^)C equals SO^'ETHI^G 
SOMPTHTKG is greater chan SAttETHIMG 
BLANKS APPEAR TO f^AKE A DIPFERENCE 
KXX 1& sreacpr than ABCDEF 

Strings can also be declared as cpnstants, as In the follovlngi 
PKOGRAtl bAZj 

CONST SAMHY ^ 'Hi there, T"iii Saim^ the String!' j 

BEG IK 

Ifl^ITELN(SAKMY) 

END. 

The use of ST&ING variables le discussed further In the next chapter. In 

connetrtlotT with the built-^ln procedures and functioita o£ Apple Pascal. 



A variable of type STRING cannot be IndeKed beyond Its current dynamic 
length* The fallowing sequEnce will reisult Iti an invalid index run- 
time error: 

TITLE:- '1236'j 
TITLEI5J :- '5' 

Beware of zero-length strings: they cannot be indexed at ali without 
causing uppredlct able results or a run-tlcie error. If a program lodexee 
a string that might have aero lengthy it ghogld first use the LRNGTfl 
function to see if the length Is Eero* If the length is zero, the 
program should not exeeute statements that index the string. See 
Chapter 3 for details on the LENGTfT function- 
Notice that a string value containinig only one character la not the same 
thing as a CHAR value; strings and CHARs are distinct data types. The 
cne exception Is Chat a string constant containing only one character 
has exactly the same foon as a CKAR constant, and such a constant can be 
used as either B CHAR value or a string value > 

You cannot define a function of type STRIWC. However, there are built- 
in functions of type STPTNC as described in the next chapter. 
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THE FILE TYPES 



A NOTE ON TERMINOLOGY 

For every file named F that is declared in a Pascal program, there is an 
automatically declared variable named F*. This is the "buffer variable" 
of the file* Some Pascal manuals also use the looser tern "window" to 
describe the way that different file records can be loaded into rhe 
buffer variable* This raanual, Instead, talks about a *'£lle pointer'^ 
aaseclated with each open file. The file pointer points to one record 
in the file, which la called the "current record." Please understand 
tbat the file pointer is not a Pagcal POINTER variable but just a 
convenient way of discussing file records, 

The following sections describe Apple Pascal"? special file features: 

the INTERACTIVE file type, untyped files, predefined files, and a 
special fornat for files of characters- 



INTERACTIVE FILES 

Like a TEXT file, an INTERACTIVE file is a file of characters. The 
difference is in the way INTERACTIVE and TEJTT files sre handled by the 

RESET, READ, and READLN procedures. 

When a t*ascal program KEADb characters from a TEXT file, the program 
must first open the file with RESET* RESET automatically perfonns a GET 
operation: that isj it loads the Eirst character of the file into the 
file's buffer variable and then advances the file pointer to the next 
character- A subaequent READ or READLN with a variable of type CHAR 
begins its operation by flFBt taking the character Chat is already in 
the bwffer variable and then performing n GET* 

If the file Is of typo INTERACTIVE Instead of TEXT, the openlt\R RESET 
does ngj, perform a GET. The buffer variable is undefined and the Eile 
pointer points to the first character of the file instead of the 
second. Therefore, a subsequent READ or FtEADLN has to be^ln its 
operation by first perfnnrlnR a GET and then taking the charecter that 
was placed in the buffer variable by the GET. 
the READ sequence used with a TEKT file. 



This ts the reverse of 



There Is one primary reason for using the INTERACTIVE type. If a file 
is not a diskette file but represents a device such as the keyboard, it 
Is not possible to perform a CET on it until a character has been 
typed* If RESET tried to do a GET, the prograra would then go no further 
until a character was typed. With the INTERACTIVE type, the progran 
doesn't perfam a GET until it is executing a READ or REAJ3tN. The 
standard predeclared flies INPUT and OUTPUT are INTERACTIVE files 
representina the console keyboard and screen; afiother predefined file 
called KEYBOARD also ropresents tlie keyboard (see the section below on 
Predefined Files) - 
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UNTYPED FILES 

In addition to the stHTidard file types and the tNTERACTIVE type. Apple 
Faecal allovs "untyped" files — objects that are declared with the votd 

FILE and nothing mare* Example: 

VAR F: FILE; 

Untyped filea can only be used With the built-in functlonfl BLOCKHEAD and 
BLOCKWftlTE for high-speed data transfers. 

An untyped file F can be thought of as a file without a buffer variable 
F"* All I/O to this file lUSt be accotnplished by BLOCKREAD and 
BLOCKVmiTE* These functions arc dGScribed In the next chapter* 



PREDEFINED FILES 

The standard predefined files INPUT and OUTPUT refer to the keyboard and 
the Screen reapectively- In addition to these, Apple Pascal ptOVidES a. 
predefined file called KEYBOARD. The difference between INPUT and 
ItEYBOARn is that when IKPUT is used to refer to the keyboard, the typed 
characters are automatically displayed on the screen; when KEYBOARD Is 
used, the characters are not automatically displayed. This allows a 
Pascal prograra to have ccmplete control over the response to characters 
typed by the user. 

All chrcG predefined files are of type IMTERACTIVE, and all three are 

autoinatically opened via RESET when the Pascal prograJH begins 
executing. 



TEXTFIUS 

The Apple Pascal system provides that a TEXT or INTERACTIVE diskette 
file that ia created with ".TEICT" aS the last part of its title has a 
special Internal ftsrtnat* Such files are called "teKtflles" in this 
manual. Oo not confuse textflles with files that are of type TEXT or 
IlfTERACTTVE but do not have titles ending in ".TEXT". 

All parts of the Pascal System that deal \ri.th files of characters (such 
as the editor) are designed to use the special tei^tflle format; and If £ 
textflle is accessed hy a Pascal program, then Che Pascal program will 
also uRe Che special format- Therefore, the normal procedure is Co use 
a title ending In "-TEXT" whenever you create a diskette flic of the 
Pascal type TEXT or INTERACTIVE. The format of a textflle Is as 
f ollows: 

At the heRlnnlng of the file Is a 102^-byte header page, which contains 
information for the use of che text editor- This space ia respected by 
all portions of the systeti. When a user Pascal program creates a 
CeKCfile (via REWRITE), che syBten will automatically create Che 

12 APPLE PASCAL LANGUAGE 



r 



E 



1: 

■1 



m 



^ 
a 



■A 



3 

d 

3 




header* When a user Pascal program accesaea an eKlstltig textflle (via 
RESET) the system skips Che header. In other wordsj the header la 
invisible to a user Pascal program using RHJKITE and RESET. 



Wlien a program uses BLOCKREAtt and BLOCKWRITE to access files* the 
special textflle structure is not respected. 

The system will tranpfer the header only on a dlskette-to-dlakette 
transfer, and will omit it on a transfer to a aerial device {thus 
transfers from diskette to fl printer or to che console will omit the 
header) < 

Following the header page, the text content itself appears in 1324-byte 
text pagea. Each text page is a sequence of llnes^ and the last line on 
a page is foUnwed by enough null charactere (ASCII 99) to fill out the 
1^24 bytes- A line is defined aa; 

pLE Indent} [textl CR 

where the braekfits indicate that the DLE and the Indent code may be 
absent and the text Itaelf may be absent. 

CR ia the "Carriage Return*' control character {ASCII 13), and may be 
absent at the end of the last line in the file- CLE is the "Data Link 
Escape" control character (ASCII 16), If present it is followed by a 
code indicating the indentation of the line- The code is 32 + the 
number of spaces to indent- Thus any leading spaces on a line are 
replaced hy the DLE and the indent cade- 

The OLE and indent code and the nulls at the end of a texC page are* 
like the header, invisible to a Pascal program- The DLE and indent are 
automatically translated to leading spaces, and vice '.^rsa* 

The end of the file ia marked by the ETX control character (ASCII 3)» 
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THE SET TYPES 



APPLE Pascal supports all of the Standard Pascal constructs for gets. 
Two llniltatloos are imposed on sets: 

- A est may not have more than 512 elements aasigned tc U. 

- A Eet may not have any INTEGERS le3s than fl or greater than 
511 assigned to it. 

A set of 512 eleinents will occujty 32 words of menioryt 

Comparlfiona and operations on sets are alloved only between sets whose 
Individual elements are of the same type. For example, in the sample 
pcogran below, the base type of the set S is the subrange type ff*.49 
while the base type of the set R is the subrange type l,.13fl. The 
underlying type of both eets la the type INTEGER, so the comparlsona and 
operations on the sets S and R in the following program are legal: 

PROGTIAM SETCOMPARE; 
VAR S: SET OF 6S..49; 
R: SET OF l.J(30i 

BEGIN 

R:- [1(8. 23, 3(?, 40, 50,6^. 70,851,3(91 ; 
IF S = R THEN 

WRITKLNC... oops -..') 
ELSE 

MRITELNCsets work'); 
S := E + R 
END- 

In the following example, the comparison I '^ J is not legal since the 
two sets are of two distinct underlying types. 

PROGRAM ILLEGAL SETS J 
TYPE STUFF=(ZERO,ONE^rWO)j 
VAR I: SET OF STUFF; 
J: SET OF S). .2; 

BEGIN 

I:- [ZERO] i 
J;- 11,2]^ 
IF I - J THEN .•, 
END. 



^<« error here 



1 



3 RACKED VARIABLES 
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PACK AND UNPACK 

Apple Pascal does not require the Standard Pascal procedures PACK and 

UNPACK, and these procedures are not provided* If a variable is PACKED, 
all required packing and unpacking are done automatically on an 
elervent -by -element basis- 



PACKED FILES 

Apple Pascal. doeE not support PACKED FILE types. A PACKED FILE can be 
declared, but the data in the filei wll 1 not actual ly be packed. 



PACKED ARRAYS 

The Apple Pascal compiler supports PACKED AHRAYs as defined in Standard 
Pascal. For exanple, consider the following declarations; 

A; ARRAT[0.*5] OF CHAR; 

B: PACKED ARRAY [0.. 9] OF CHAR; 

The array A will occupy ten 16-bit words of memory, with each element of 
the array Odcupylng one word. The PACKED ARRAY B on the other hand will 
occupy a total of only 5 words, since each 16-bit word contains twu 
8-bit characters* Each element of B is S bits long- 

PACKED ARRAVa need not be restricted to arrays of type CHAR, For 
exa tuple ; 

C: PACKED ARRAY 13*. 1] OF 0*.5; 

E! PACKED ARRAY [1*. 9] OF SET OF 0*.n; 

D2: PACKED ARRAY [fl. . 239, 0. . H9] OF BOOIEANj 

Each element of the PACKED ARRAY C is only 2 bita long, since only 2 
bita are needed to represent the values in the range 3.»3, Therefore C 
occupies only one 16-blt word of metioryt and 12 of the bits In that word 
are unused. The PACKED ARRAY D is a 9-ward array, glnce each element of 
D is a SET ^rtiich can he represented In a minimum of 16 bits. Each 
element of a PACKED ARHAV OF BOOLEAN, such as D2 in the above QK^imple, 
occupies only one hit. 



J 
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The details of exactly how vaxlablea are packed are unspecified- In 
most cg.SB^t the niiniTiiuri space incn which an array can be packed ia one 
vord (cwQ eight -bit bytes) - For example, consider 

BITS: PACKED ARRAY [ff.* 7] OF BOOLEAMj 

This ia an Gighc-eleinent array where each element requires one blt» so 
you might expect it to occupy eight bits or one byte. In fact, It 
Dccuptes one wqrd or two bytes. Furthermore, the two-dlmenslGnal array 

SATS; PACKED ARRAlfl^..^] OF PACKET] ARKATE0.*7] OF BOOLEAN; 

or Its e'quivalent 

BATS: PACKED AHRAY [3. . 3,0. * 7] OF BOOLEAN; 

[:onaist:B of four arrays* Each of chein, like the previous array, 
Occupies one word- Therefere BATS occupies four tfardE» 

Note Chat a PACKED ARRAY OF CHAK always occupies one byte per character 
and a PACKED ARRAY OF P**255 always occupies one byte per element- 
Also » packing never occurs across word boundaries* Thle ineans that if 
the type of element to be packed requires a nuiaber of bits which do4:S 
not divide evenly Into 16» there will be soiae vmused bits in each of the 
Words where the array is stored* 

The following two declarations are NOT equivalent because of the way the 
Pascal Compiler is impleniented: 

Ei PACKED ARRAY [(I. • 9) OF ARRAY [0**3] OF CHAR; 
7i PACKED ARRA¥[?..9,3..3] OF CHAR; 

In the declaration of E, the second occurrence of the reserved word 

ARRAY cfluaes the packing option in the couipller to be turned off- E 
becomes an unpacked array of ^0 words. On the other handj the PACKED 
ARRAY F occupies only 2(J words because the reserved word ARRAY occurs 
only once in the declaration- If E Is declared as 

E: PACKED ARRAY [fl. .91 OF PACKED ARRAY [0.-3] OF CHAR; 



E; AREAy[(J..91 OF PACKED ARRAY [0.. 3] OF CHAR; 

F and E will have identical conf igurations- 

In declaring a PACKED ARKAY, the word PACKED is only raaningful before 
the last appearance of the Word ARRAY in the declaration* I-Jhen in 
doubt, a good rule of thumb far declaring a nulcicjli^ensianal PACKED 
ARRAY is to place the wfjrd PACKED before every appearance rf the word 
ARRAY to ensure that the reBuItant array will be PACKED, 



I !^ 
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The array will only be packed if the type of each element of the array 
la scalar, subranRd or a set and each array element can be represented 
In fl bits or fewer* For an array whose elementa are sets^ this ntaans 
that the underlying type of the set rouat not contain more than S 
elements, and miat not contain any Integer greater than 255* 

The following declaration will result in no packing whatsoever because 
the final type of the array cannot be represented in a field of S bits: 



C: PACKED ARRA¥ffl..3] OF fl, - 1 

G will be an array which occupies four 16-blt words. 

Note that a string constant nsy be iaasigned to a PACKEJD ARRAY OF CHAR 
at It has exactly the same length), hut not to an unpacked ARRAY OF 

CHAR, Likewise, comparisons between an ARRAY OF CHAR and a string 
constant are illegat- 

Becaiise of their different sizes, PACKED ARRAYs cannot be coftipared to 
ordinary unpacked ARRAYs. 

A PACKED ARRAY OF CHAR may be printed out with a single write stateinent 
(exactly as if it were a string): 

FROGRuAM VERYSLICKi 

VAR T: PACKED ARRAY 13, , 10] OF CHAR; 

BEGIM 

r:''EELLO THERE'j 

WRlTELNfT) 
END. 



PACKED RECORDS 

The folloving RECORD declaration declares a RECORD with four fields* 
The entire RECORD occupleB one 16-bit word as a result of declaring It 

to be a PACKED RECORD. 

VAR Rj PACKED RECORD 

I,J,Kj 0.,3l; 
B: BOOLEAN 
END; 

The variables 1, J, K each cake up five bits In the word. The boolean 
variable B Is allocated to the 16th bit at the same word- 

In mich the same iDflnner that PACKED ARRAYa can he Tnultidimeneional 
PACKED ARRAVs, PACKED RECORUS may contain fields which themselves are 
PACKED RECORDS or PACKED ARRAYS. Again, slight differences in the way 
in which declarations are made will affect the degree of packing 
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achieved » for example, note that the following two declarations are not 
equivalent ! 



VAK A: PACKED RECORD 
C: INTEGER J 
F: PACKED RECORD 

R: CHAR; 
K: BOOLEAN 
ENB: 



VAR B:PACK:eD KECOEUJ 
C: INTEGER; 
r : RECORD 

R:CHAR; 
K: BOOLEAN 
END: 



H: PACKED ARRAY [fl*. 3] OF CHAH 
END; 



H: PACKED ARRAY! 
END; 



■ 3] OF CHAR 



Afl with PACKED ARRAYS, the word PACKED should appear with every 
occurrence of the word RECORD In order for the FACKflP KECOEID to retain 
its packed qualities throughout all fields of the RECORD, In the above 
exantplcp only RECORD A has all of its fields pecked into one word. In 
B, the F field is not packed and therefore occupies two 16-blt iifords* 
It Is iniportafit to note that d packed or unpacked ARRAY or RECORD uhich 
Is a field of a PACKED RECORD will always start at the boelnnlng of the 
next word boui^dary. This ciedds that in the case of A, even Chough the F 
field does not completely fill one word, the H field starts at the 
beginning of the next word boundary- 

A ease variant loay be used as che last field of a PACKED RECORD, and the 
araount at apace allocated to It will be che sl^e of the largest variant 
among the various cdaes> The actual nature of the packing ±3 beyond the 

Scope a£ this docutnent^ 

VAR K: PACKED RECORD 

B: BOOLEAN; 

CASE F: BOOLEAN OF 

TRUE: (Z: INTEGER); 

FALSE: (M: PACKED AimAY[0,,3i OF CHAR) 
ETifD; 

In che above example the B and T fields are stored In two bits of the 
first Ife-blc word of the record. The remaining fourtoen bits are not 
used* The alze of the case variant field Is always the slEe of the 
largest Variant , so In the above example, the case variant field will 
occupy two Vfords- ThuK the entire PACKED RECORD will occupy three 
words- 



USING PACKED VARIABLES AS PARAMETERS 

No PACltED variable may be passed as a VAR (call-^by-reference) parameter 

tc a PROCEDURE or FUNCTION. Packed variables may, however, be passed as 
ordinary calJ-by-value parameters. 
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THE LONG INTEGER TYPE 



In Apple Psecal, the predefined INTEGER type can be modified by a length 
attribute as in the fcllowlng examples: 

TYPE BIGNUM - INTEGERI12]; 
VAR FATS; INTEGER [25h 

This defines BIGNim as a type which can have any integer value requlrltig 
not more tliflu 12 deeimal digits^ FATS can have any integer value 

requiring not acre than 25 .digits. The length attribute can be any 
unsigned INTEGER constant up to and Including 36. 

This IB a new kind of type, which is called a LONG INTEGER in chle 

manual. The LONG INTEGER is suitable for business, scientific or other 
applicatlpiis which need extended number lengths with complete accuracy. 
A LONG INTEGER is repreaenCed intsmaHy as a binary-coded decimal (BCD) 
number; that is, each decimal digit of the value le represented In 
Iji^apy. This means that there can be no rogndinE errors in working with 
LONG INTEGER values- 

LONG INTEGER conetants are also allowed* Any integer constant whose 
value eitcceds MAXINT is aucomatically a constant of the type LONG 
INTEGER. 

The integer arithmetic operations [+, -, *, and DIU) can all be Ltsed 
wltll LOWC INTEGEfi values. However ^ MOD cannot be used ViCh LflNC 
INTEGERS. In integer arithemetic, overflow occurs if any intermediate 
or final result requires mote than 36 declTtiaX digits. When a LONG 
INTEGER value la assigned to a LONG INTEGER variable, overflov occurs if 
the vslue requires more declnal digits than the defined length of the 
variable. 

An INTEGER value can always be assigned to a LONG INTEGER variables it 
is automatically converted to the appropriate lensth- However, a LONG 

INTEGER value can never be asalsned to an INTEGER variable- If INTEGER 
and LONG INTEGER values are mixed in an expression, the INTEGER values 
are converted to LONG INTEGER and the result is a LONG INTEGER value- 
LONG INTEGERS and REALs are incompatible; they can never be mixed in an 
arlthnieClc expression or assigned to each other. 



All of the standard relational 
INTEGER and INTEGER values. 



perators may he ueed with tnixed LONG 



The bullt-lti procedure STR accepts a LONG INTEGER value as a parameter, 
and converts it Co a string of decimal digits. The built-in function 
TRUNC accepts a LORG INTEGER value as a parameter, and returns the 

corresponding INTEGER value if the absolute value of the LONG INTEGER is 
less than or equal to MAXINT. These built-lns are described in the next 
chapter; they are the only built-ins which accept LONG INTEGER 
parameters. 
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An attempt to declare a LONG INTEGER in a parameter list will result iti 

a syntax error. This restriction caay be circumvented by defining a type K 

which Is a LONG INTEGER. For example: fe 

TYPE lAim = INTEGER(L83; B 

PHacEDLTRE BICWUMBER (BANKACCTt LONG); 



EXAMPLES: 

VAR I: INTEGER; 

L: TNTEGER[N3i {Where N is m. Integer constant <-^ 36 } 

R; REALi 

I:- L {syntax error; the TRDNC function can be used to convert a 

LONG INTEGER to an INTEGER > 
Li'^-L {correct. If ^L doea not require irore than 36 digits; the 

TDiniiB sign doesn't count as a digit) 
L:- I {always correct) 
Lj" R {never acitepted) 
R:" L {never accepted} 

The nicraory apace allocated for a LONG INTEGER la always an integral 
nuinber of ucrds> Specifically, a variable of type INTEGER,[n] Dteupiea 

fn + 3) DIV A +1 

words- 

Therefore, the actual limit on the value of a LONG INTEGER may exceed 
the nuraber of decimal digits specified In Its declaration* For examploj 
a length of 5 through 8 occupies three words and can store values up to 
and Including 99999999^ a length of 9 through 12 occupies four words and 
can Store values wp through 9^9999999999^ a length of 13 through 16 
occupies five words and can store values up through 9999999999599999. 




CHAPTER 3 

BUILT-IN PROCEDURES 
AND FUNCTIONS 



String Bullt-Ine 

The LENGTH Functl* 

The POS Function 

Tile CONCAT Function 

The COPY Function 

The DELETE Prccedure 

The INSERT Procedure 

The STR Procedure 
Input and Output BuiXt-Ina 

Overview of Apple Pascal I/O J'acllltles 

The REWRITE Procedure 

The RESET Procedure 

The CLOSE Procedure 

Thr EOF Function 

The F^LN Function 

The GET and PUT Procedures 

The lORESlTLT Function 

Introduction to Text I/O 

The READ Procedure 

READ With a CHAA Vflrlable 
READ With a NumcHc Variable 

The READLW Procedure 

The WRITE and WRITELN Procedures 

The PAGE PrccEdure 

The SEEK Procedure 

The UNITRCAD and UNITWtlTE Procedures 

Tlie UNITBUSY Function 

Tlie UNITWAIT Procedure 

The UNITCLFJW Procedure 

The BLOCKREAE and BLOCKWRITE Functions 
Klaccllsneous Bullt-lns 

The ATAN Function 

The LOG Function 

The TRimc Function 

The PWROFTEN Function 

The MARK and RELEASE Procedures 

The HALT Procedure 

The EXIT Procedure 

The MEHAVAlL Function 

The COTOXY Procedure 

The TRERSEARCH Function 
Byte-Oriented Bullt-Iaa 

The STZEOF Function 

The SCAfJ Function 

The MOVELEFT and HOVERICHT Procedures 

The FLLLCHAR Procedure 
SiLfliBiary 
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This chapter describes all Che built-in procedures and functltjtia of 

A,pple Pascal that differ from Standard Pascal- This does not include 
the procedures and functions that are provided as library tJNITa, e.g, 
the graphics procedures and functions* Chapter 7 covers the Library 
UNITh. provided with Apple Pascal- 

Transcendental functions (e^g. the trig functions SIW, CQ3, etc.] are a 
special case* In Standard Pascal they are built-in functions, but in 
Apple Pascal chey are in a library UNIT, The ATMi and LOG functions 
differ slightly from Standard P&acal, and they are described in this 
chapter* The other transcendentals differ only in that to uae them your 
prosram must Include a USES TRAl'^SGEND atateraent as described In 
Chapter 7. 



Since some of these built-in procedurea and functlona do no checking for 
range validity of parameters, they may easily cause unpredictable 
results. Those hutlt-ins which are partlcularlly dangerous are noted as 
auch in their descrlptinns- Any necessary rar^ge or validity checks are 
your responsibility* 



STRING BUILT-INS 



In the following descriptlonst a "string value''' tne^ns a atrlng variable, 
a quoted string, or any function or expression whose value la a string. 
Unless athervise stated all paranetera are called by value- 



THE LENGTH FUNCTION 

The LENGTH function recurna the integer value of the length of ^ 
string* The forcn is 

LENGTH (STRG) 

where STRG l9 a string v«lue. Extmple: 

GEESTRINC != '1234567'; 

WRITELN( (LENGTH (GEESTRING), ' ', LENGTH(''3> 

Thla will print; 
7 9 



22 APPLE PASCAL LANGUAGE 



M 
ji 
3 

i 

A 

I 
E i 

a 

4 

I: 'd 



THE POS FUNCTION 



The POS function returns an inteRer value* The form is 

POS (SUBSTRG, STRC) 

where both SUBSTRC and STRC are string values* The E*Q5 function scans 
STRG CO Elnd the first occurrence of SUtiSTRG within STRC. POS returns 
the Index within STRG of the first character in the notched pattern* If 
the pattern is not found» POS returns zero- Example: 

STUFF 1= 'TAKE THE BOTTLE ^TH A HETAL CAP'; 

PATTERN := 'TAL'; 

MEITELN( POS (PATTERN, STUFF) ) 

This will print: 

26 



THE CONCAT FUNCTION 



The COtiCAT function returns a String value- The form Is 

CONCAT { STRGs ) 

where STRGs means any number of string values separated by commas. This 
function returns a sErinR which is the concatenation of all the strings 
passed to it> Example: 

SHORTSTRING :- 'THIS IS A STRINCi'; 

LONGSTRING := 'THIS IS A VERY LONG STRING.'; 

LOMGSTRINC := CONCAT ( 'START \ SHORTSTRING, '-', LOMGSTRING)} 

WRITELIULONGSTRINC) 

This will print: 

START THIS IS A STRING-THIS IS A VLf^Y LONG STRING. 
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THE COPY FUNCTION 

Ttie COPY function returns a string valk*©. The form Is 

COPV (STRG, INDEX, COUNT) 

where STRG Is a atrinj? value and both INDEX and COUNT are integ&r 
values* This function returns a string containing COUNT characters 
copied frora STRG starting at the INDEXth position in STRG. Example: 

TI, != 'ECEEP SOHKTHXNK HERE'; 

KEPT s- COPV(TL, POS('S% TI.), 9); 

WRITKLIHKEPT) 

Thi3 will print; 
SOMETHING 



THE DELETE PROCEDURE 

The DELETE procedure cnodlflGs the vqIue of a string variable* The form 
is 

Da.ETE (STRG, INDEX, COTOT) 

Uhere STRC Is a string variable called by reference and Bodilied, and 
both INDEX and COL'NT are integer values- This prneedure reinoveB COUNT 
characters fcom STRG starting at the ItlDEX specified. ¥^xanplc: 

OVESSTL^FPED :» "THIS STRING HAS FAB TOO IIAITY CHARACTERS IN IT. "j 
DELETE (OVERSTUFFED, PQSCHAS'. OVERSTUFFED )+3, B); 
MRITELN (OVERSTUFFED) 

This will print: 

THIS STRING HAS HANTT CHARACTERS H IT. 
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THE INSERT PROCEDURE 



The INSERT procedure modifies the value of a string variable* The form 

i5 

INSERT (SUBSTRC, STRG, INDEX) 

where SUBSTEC is a string value, STRG la a string variable called by 
reference, and INDEX is an integer value- This inserts SUBSTRC Into 
STRG at the INDEXtb position In STRG* Example: 

ID := 'INSERTIONS'; 

MORE != ' DEMONSTRATE*; 
DELETE (MORE, LENGTH (MORE) , 1); 
INSERT(MORE, ID, ROSCIO', ID)); 

WRTTELN(TD) 

This will print: 

INSERT DEMONSTItATIONS 



THE SIR PROCEDURE 

The STR procedcre mndifies the value Of a String i/ariable* Ttie form is 
PROCEDURE STR ( LONG , STRG > 

where LONC is an Integer value, and STRG la a string variable called by 

reference. LONG may be a LONG IMTEGRR* 

This converts the value of LONG into a atrfng^ The r^aulting string is 
placed in STRG, See Chapter 2 for nore about the use of LONG INTEGERS, 
Hxantple' 

INTLONG := l32fl395S?3; 

STRCINTLONG, INTSTRING); 

INSERT ('.', INTSTRING, LENGTH (INTSTRINC) -I ) ; 

WRITELNC'S', INTSTRING) 

This will print; 

$1020395.03 

The following proEram segtient will provide a suitable dollar and cent 
rDucitse: 

STRa,S)j INSERT{'>',S,LENGTH[S)-ni WRITELN(S) 

where L and S are appropriately declared* 
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INPUT AND OUTPUT BUILT-INS 



OVERVIEW OF APPLE PASCAL I/O FACILITIES 

This Bsctlon deals with data transfers to and from al3 peripheral 
devices^ includtng diskette driveSj the screen, the keyboard, prltiters^ 
&tc. There are also certain "integral" devices such as the TTL j^-ams- 
contTol outputs and the built-in speaker, which are not considered ae 
I/O devices^ see Chapter 7- For complete information on Apple Pascal 
file types, see Chapter 2, 

Apple Pascal I/O facilities can be thought o£ as exlstinfi at four 
different levels £ 

- Hardware-oriented I/O: the UNITREAD, UNITWRlTE, and UNITCLEAH 
procedures are the lowest level of control- They allow a 
Pascal pTogram to transfer a apeciEiod number of consecutive 
bytes between raemory and a device- They are not contfolled by 
filenames, directories, etc-, but merely use device numbers 
and (for diskette drives) block numbers- 

- tTntypcd file I/O; The BLOCKHEAD and BLOCKWRITE functions 
provide 1/0 fot untyped files (see Chapter 2). They make use 
of filenames and directories but consider a file to be DErely 
a sequence of bytes — not a sequence of records of a 
particular type. 

- Typed file I/O: The GET, PUT, and SEEK procedures treat a file 

as a sequence of records* GET and PUT provide transfers 
bEtween Individual file records and the file's buffer 
vijriable, and SfIEK moves the pointer to a apeciflcd record 
within the file. The EOF function provides an indication of 
when the end of the file has been reached. 

- Text file I/O: The fi£AD, READLN, WRITE, and WRITELN procedures 

provide transfers between a file of type TEXT or INTERACTIVE 
and proBr^"^ variables. The PAGE procedure writes a 
top-of-fortu control character Into a textfile. The EOLN 
function provides an indication of wtien the end of a test line 
has been reached- This is the highest level of 1/0 control, 
with many sophisticated features . 

As mentioned In Oiapter 2, the INPUT, OUtPLiT, and KEYBOARD files are 
predefined and need not be declared in a program- All other files nust 
first be declared in the VAR section of a program, and must then be 
opened by means of RESET nr REWRITE before Chey can be used in any way. 

Opening a file is a means of associating the file's identifier (deciarec 

in the program) with its title (used by the operating system)* If the 
file to be used does not already exist, open It with REWRITE; this 
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cauees the operating system to create a directory entry for the file- 

If FEWftlTE is used with the tide of an existing file, the existing file 
Is destroyed and a now directory entry is created. RESET is used to 
open an existing file and can also be used to tnove the file pointer back 
to the beginning of a file that ie already open* A CLOSE procedure is 
also prcn.-'lded* It offers several options for the disposition of the 
file when the program is through using It- 

If an I/O operation ia unsucqoaaf ul , the aperatlng syeten will nortnally 
tetxilnate prograo execution. However, there is a. compiler ciption to 
disable this feature* The lOpESULT function allows Lhe progr'!™ itself 
to check on the etatus of the most recent 1/0 operation and take 

appropriate acr Ion- 



THE REWRITE PROCEDURE 

This procedure Ltrescos a new file and warks the file as open- As 
explained below. It can also be used to open an existing file. The 
form Is 

REWRITE ( FILEID , TTTtE ) 

where FILEir Is the identifier of a previously declared file, and TITLE 
Is a string contalninj< any leeal file title* 

If the device specified in the TITLE la not a diskette, then the file is 
opened for both input and output. If the TITLE indicates e diskette 
file, BEWPITE freaCes a new file and opens it for input and output. 

If the file is already CFpen, an 1/0 error occurs (see lORESULT below). 
The file regains open- 

An examplG showing the use of KEWEITE In a progtaci follows the 
descrlptlDd of GET and PUT below* 



THE RESET PROCEDURE 

This procedure opens an exlstlnp file for both reading and writing* 
There are two forms: 

RESET { FILEID , TITLE ) 

RESET t FILEID ) 

where FILEID is the identifier ftf a previously declared file, end TITLE 
1b a string containing any legal file title- 

If a TITLF is used and the specified file is already open, an I/O error 
occurs (see lORESDLT, below)- The file's state remains unchanged- If 
the file doea not exist, an I/O error occurs* 
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A BESET without the TlTI.F dan only be used on an open file; the effect 

Is simply to reposition the file pointer as if the file had Just been 
opened - 

If the file Is not of type INTERACTIVE, RESET autDmaclcally performs a 
GET action — that is^ it loads the first record of che file Into the 
file's buffer varleble and advanc.ee the file pointer to the second 
record, tf the file is INTERAaiVE, no GET ie perfomed; the buffer 
variable's value is undeflne*3 and the file pointer points to the first 
record, CCET is described further on,) 

Note that RESETting a non- INTERACTIVE file to an output-only device, 
such as PRINTER:, inay cause b run-time error a^ s result of the 
automatic GET caused by the RESET. 

When an existing file is opened with RESET and Is then used for output, 
only the file records actually written to are affected- 

An example sbowing, the use of RESET In a program followis the description 

of GET and PUT below- 



THE CLOSE PROCEDURE 

This procedure closes a file which was previous! 
REWRITE. The form is 

CLOSE ( FILRIU [, OPTION] ) 



opened with RESET or 



wliere flLEID Is the identifier of a prevlouBly declared file, and OPTION 
t^y be any one of the following: 

NORMAL — a normal close Is done, I.e. CLOSE elraply sets the 
file state to closed. If the file was opened using PEUT^ITE 
and Is a disk file, it is deleted from the directory. 

LOCK — the file is made pemanenc in the directory if the 
file is on a disk and the file was opened with a REWRITE; 
otherwise e NORMAL cloee la done. If the TITLE matches an 
existing diskette file, the original concents of the file are 
lost ^ 

PURGE -- If the file Is s diskette file, It is deleted from 
the directory* In the special case of a diskette file that 
already exists and Is opened with REVRITE, the original file 

retnains in the directory, unchanged. If the file is not s 
diskette flle^ the associated unit will go off-line. 

CRUNCK — this is like LOCK except that tt locks the 
etid-of-f ilc to the point of last access, i.e. everything flfter 
the last element accessed Is thrown away* If the TITLE 
[Hatches an e^dsting diskette flle» the original contents of 
the file are lost. 
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If IW OPTION is oraittedj the KORJiAL close la performed. 

All CLOSES regardless of the option will mark the file closed and will 
mekc the file buffer variable FTLEID~ trndefined. CLOSE on a CLOSEd file 
causes no action. 

An example showing the use of CLOSE in a program follows the description 

of GET and Pt.1T below. 



THE EOF FUNCTION 

This function returns a BOOLEAN value Co Indicate irfiether the end of a 

specified file has been reached. When EOF is true^ nothing more can be 
read from the file. The form Is 

EOF [ ( FILEID ) I 

If {FILEID) ie not present, INPUT is assumed. 

EOF is false Infwdiately after the file is opened, and true on a closed 
file. Whenever EOF (FILEID) is true, FTl.FTn" is, undefined. 

After a CET, EOF is true if the GET attempted to access a record that la 

after the end of the file* After a PUT or WHITF* EOF is true if the 

file cannot be expanded to acconirrodate the PUT or UTitTE (because of 

limited diskette space, for exairiple). 

For details on EOF after a REAE or REABIN operation, see the 

descriptiona of REAC and READLN further on In this chapter, and 
Appendix C. 

When EOF becoires true during a RFAU or GET operstlon, the value of 
FILEID" IB not defined - 

When keyboard input is being read (via the predefined files INPUT or 
KEYF!OARI>), EOF only becpnes true when the eftd-of-f±ie character ifi 
typed. The End-of-flla character is ctrl^C (ASCII 3). EOF remains true 
until the file IHPLT or KEYBOAPJ) is KLSET, and no more typed characters 
can be read until this is done. 

An example showing the use of EOF In a program follows the deeerlption 
of RET and PUT below. 
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THE EOLN FUNCTION 

EOLN Is defined only for a flic of type TEXT, FILE DF CHAR, or 

INTEitACTIVE. This function returns a BOQLKAN value to Indicate whethEr 

the painter for a specified text file Is at the end of a line Th*. 

form is ^ 

EOLN [ t FILEID ) ] 

IJ: {I'LLEilJJ Is cioc presont, INPUT is assumed. 

EOLU returns false Imniedlately after the file Is opened, and true an a 
closed file. 

When a GET finds an end-of-llne character ^the CR character, ASCII 13) 
in the file, it seta EOLN to true. Instead of loading the end-of-llne 
character Into the file's buffer variable it loads a. apace (ASCII 32), 

For Che behavior of EOLN after a READ or REAULW, see the descriptions of 
these statements furtlier on. 



THE GET AND PUT PROCEDURES 

Theet procedures artj used to maii or write one logical record from or to 

a typed file. The forms are 

GET ( FILEID ) 
PUT ( FILEID > 

where FILElu is the identifier of a previously declared typed file- A 
tipped file is any file for which a type is specified In the variable 
declaraclodj. aa opposed to untyped files tsee t^hapter 2). 

GET £FILEIU) advances the file pointer to the next record and moves the 
contentti of this record into the file buffer variable FILEtU". The next 

Gi^ or PUT with the aarae FILEU) will a^^cess the next record in 
sequence. 

PUT (FILEID) advances the file pointer to tJie next record and puts the 
coiitenta of FILElu" Into this record. The next GET or PUT wltli the same 
FILEIU will access the next record In sequence* 

The actual phydlcal disk access caay not occur until the next time the 
physically associated block of the disk Is no longar considered the 
current working block. The kinds of operation which tend to force the 
block to be urltten are; a SEEK to elsewhere In the file, a RESET, and 
CLOSE, Successive GETs or PUTs to the file wl U cause the physical I/O 
to happen when the hlock boLtndarles are crossed. 

The following; two exataple programs iUustrate the use of REWHITE, RESRT, 

CLOSE, EOF, LJET, and PUT, The first prograra cregtt^g a new file of type 
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KEAL, with th« title REAL. DATA, and puts ten REAL values into it- The 
values are supplied by the user* 

To obtain the values, the program uses a WRITE tt^ display a prompt on 
the screen and a READ to accept the value typed by the aser- RF*AD and 
WRITE are described in detail further on in this chapter* 

FKUGRAM MAJtEFILE; 

x'ar f! file. of real; 

1: integer; 

BEGIH 
{*Open With REWRITE since this is a new file.*) 

REWRITE(F, '*REALS.DATA'); 
(*Read 10 numbers and store them in the file.*) 

FOR l:-! TO 10 DO BEGIN 
(*PLit a proiM^t on the screen**) 

WRITE C'~->')i 
(*Read a number from the keyboard.*) 

aEAU(F-); 
C*3tore the number in the f i le < * ) 
PUT<F) 
END; 
(♦Close the file and lock It.*) 
CLOSE (F, LOCK) 
END. 

The second progrscn reads values from the file created by the first 
program, and displays them on the screen- 

PROCRAM READFILE; 

WAR F: FILE OF REALj 

BEGIW 
(*Open with RESET since we want to read the file*) 

RESET(F, '*REALS.DATA'); 
(*Read each number from the file and display them*) 

WHILE NOT EJOF(F) DO BEGIN 
(*DJsplay tUe current number on the screen*) 

WRITELNCF^Jj 
{*Advflnce to the next number*) 
GETCF) 
END; 
{*Clofle the file*) 

CLOSE (F) ^_^ 

END. 

Note that these programs offer na flexibility as to the title of the 
file. The exaiHple under REAULN helow shows how to let the user specify 
the title of the file to be used. 
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THE lORESULT FUNCTION 

This function returns en InCeger value which reflectfl ttio statue of the 
last completed I/O operation* The form Is 

lORESULT 

The values returned by lORESULT are as foHovs (also see Table 2): 




1 
2 
3 
4 



7 
8 
9 

a 

12 
13 

u 

15 
16 



No error; normal I/O completion 

Bad block on diskette (not used on Apple) 

Bad device fvolusie) number 

Illegal operation (e.g., read from PRINTER;) 

Unknoiifn hardware error {not used on Apple] 

Lost device — no longer on line 

Lost file — file is no longer In directory 

Bad title — Illegal fllenarae 

No room — insufficient space on diskette 

No device — volumie is not on line 

Ho sLich file on specified volume 

Duplicate file title 

Attempt to open an already open file 

AttenipL to access a closed file 

Bad input format — error in reading real or integer 

Ring buffer overflow — input arriving too fast 

Write-protect error — diskette is write-pratGct ed 

Device error — bad address or ddCa on diskette 






In nonoal operation, the Compiler will generate code to perform nm^ 
time checks after each I/O operation except UNITREAD, UNITWRITE, 
BLOCKREAD, or BLOCKWRITE. This causes the program to get a run-tine 
error on a bad I/O operation* Therefore If you want to check lORESULT 
with your ovn code in thq program, you must disable this compiler 
feature hy using the (;*$1-*) option (see Chapter 4). 

Note that lORESULT only gives a velid return the first time It le 
referenced after an I/O operatlcn* If It is referenced again fwithout 
another I/O Operation), It will always return 0> 



^ 
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INTRODUCTfON TO TEXT I/O 
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In addition to PUT and GET, Apple Pascal provides the standard 
procedures READ, READLS, WRITK» and WEITELN, collectively known as the 
text I/O procedures. They perform the same tasks as in standard Pascal 
and have the eaitie syntax (with the addition of STRING variables). 
Howevetj the details of their operation are specific Co Apple Pascal and 
can be conpUcated. Also, the tise ol STRING variables and ttte 
dietinction between TEXT and INTERACTIVE files have in^sortant effects. 
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The text t/0 procedures can only be used with files of type TEXT or 
INTERACTIVE. As already mentioned, RESET makes a distinction between 
these two Hie typea: when a TEXT file is RESET, a GET is automacically 
performed but when an I^fTERACTIVE file is RESET, no GET is performed. 
This requires READ and READIN to be rather complex procedures. Like 
many other complex creatures, they will behave siniply if you use them 
slniply* Therefore, this manual is written with some assumptions in mind 
about how they will be used. These assumptions can be translated into 
the following specific suggestions: 

- When using the text I/O procedures don't use GET or PUT, and 
don't cefer explicitly to the file buffer variable F". The 
reason is tliat the text I/O procedures themselves use GET and 
PUT in complicated ways- 

- Don't mix reading and writing operations on the same diskette 
teKtflU. If you read from a tentfile, CLOSE It and recpen it 
before writing Co it; and vice versa. 

- To open an existing diskette textfile for reading, always use 
REiiET. To open an existing diskette textflle for writing, 
always use SJlWRITE. 

- Con't use READ with a STRING variable. Use READLH* 

- Don*t use the EOLN funcclon with REA0LM, and don't use it with 
STRING variables. 

If you follow these suggestions, the text 1/0 procedures will work 
exactly as described in the following pages. These are not rules of 
Pascal; there is nothing in the system that will enffirce them. However, 
the eKact details of what happens if you ignore the suggestions are 
beyond the scope of this chapter. 

There may be situations in which these assumptions and suggestiona are 

too restrictive. If so, you will need the conplete details on how t<EAD 

and READLT^ behave In all possible situations, as given In Appendix C 

In particulari you need the information in /^pendix if you want to tcix 
reading and writing operatione or overwrite part of an existing text 

file without destroying all of the original contents. 



THE READ PROCEDURE 
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This procedure may be used only on TEXT (FILE OF CHAR) or INTERACTIVE 
files. It allows chaiTHctera and numeric values to be read from a file 
without the need for explicit use of GET or explicit reference to the 
window variab IS' The forra is 

FROCEBURK READ ( I FILEin, ] VBLs > 

where FlLEtO is the Identifier of a TEXT or INTERACTIVE file which must 
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be open. If Lhe FILETD Is omltced, IWFUT Is assumed- VBLs iBeans one or 
more variables separated by cofnmas. The variables inay be of type CKAH 
STHIMG, INTEGER, LONG INTEGER, or REAL, (But ^du should use READLN for 
STRING variables), 

READ reads values from the file and assigns them to the variables In 
sequence. 



READ With a CHAR Variable 

For n CHAR variable, R^VirJ reads one character from the file and assigns 
that character Co the variable^ ThcicD are tvo special caaee r Whenever 
the end-of-Hne character (ASCII 13) is F£AD* the value eBslgned to the 
CHAR variable is a apace (ASCII 32), riot a CR, Whenever EOF becoines 
true, the value assigned to the CHAR variable is not defined* 

After the READ, the next READ or REAOLN will always start with the 
character innnedlatcly foUowiTig Che one Just RSAD ♦ 

The Workings of EOLK and EOF depend trn whether the file is of type TEXT 
or INTERACTIVE* For a TEXT fiU, EOF is true when the last text 
character In the file has been READ* EOLN is true when the last text 
character on a line has been READ and whenever EOF is true- (A "text 
character" here t^aoa a character chat is not the end-o£*llne character 
or the end-of-f lie character' ) 

For an INTERACTIVE file, EOF is net true until the end*of-£ile character 
has been READ- EOLN is noc true until the ond-of-llne character at the 
end of the line has been READ or until EOF Is true:. 

If you are using EEAD with a CHAR variable and you need to use EOLN, you 

may be able to simplify the situation by usina E.EADLN with a STRING 
variable Instead; this gives you line-crlentcd rejadlng wlthoyt the need 
to check EOLK fseo below) p 



READ Wjth a Numeric Variable 

For a variable of one of the numeric types, REAT expects to read a 
String of characters which can be Interpreted as a numeric value of the 
same type. Any space or end-o£-line characters preceding the numeric 
string are skipped; and 3 epace, end-of-line, or end-of-flle Is expected 
after the numeric etrlng. If a numeric string Is not found after 
ekipping spaces and ond-of-lines, an I/O error occurs* Otherwise, the 
(String Is converted to a numeric value and the value Is assigned to the 
variable- 

After the READ, the ne>st READ or REAPLN will always gtart with the 
character inunedlatcly following the last chariicter of the numeric 
string. 
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If the last character o£ the numeric string is the last character on the 
line, then EOLN will be true* If the last character of the numeric 
string is the last character in the Eile, then EOF and EOLN will both be 
true- 

IE nothing but spaces are found before the EOF, a iralue of ff is READ. 

Nsste that the behavior of READ with a numeric variable le exactly the 
same regardless of whether the file is TEXT or INTERACTIVE, 



THE READLN PROCEDURE 

This procedure tdev be used only on TEJTT (FILE OF CHAR) or INTERACTIVE 
files. It allows line-oriented reading of characters, strings, and 
numeric values » The Eomt Is 

PROCEDURE READLN ( [ FILEIDj ] VBLg ) 

vhere FILEID Is the identifier of a TEXT or INTERACTIVE file i^leh tmst 
be open. If the FILEID is omitted, INPUT is assumed. VBLs tueane one or 
more variables separated by comiQas* The variables nay be of type CHAR, 

STRlNt;, INTEGER, LONG INTEGER, or REAL, 

READLN works exactly like READ, except that after a value has been read 
for the last variable, the remainder of the line is skipped (Including 
the end-of-line)- After any READLN, the next READ cr READLN will always 
Btart with the first character of the next line^ if there is a next 
line. If there is no nest line, EOF will be true. 

REAQLK with a STRISJC variable reads all the characters up Co but not 
including Che end-o£-llne character. Thus repeated READLN's with a 
STRlNO variable have the effect of reading successive lines of the file 
as strings. 

One of the raost conmion uses of READLN with a STRIMG variable la co read 
a strlnf^ of characters from the CONSOLE: device. In the following 
exatnple, which is a modification of the previous example under GET and 
PUT, READLN is used to read a filename typed by the user: 
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PROGRAM MAKEFILE; 

VAR F: FILE OF REAL; 
l! INTEGER; 
TITLE: STRING; 

BECIN 
(*Ask user for title.*) 

WEITECType narae of file: '); 
(•Accept line typed by usee-*) 

READLN (TITLE); 
<*If title has no suffix^ add .DATA suffls,*) 

IF 1*05 C-S TITLE >^J THEN TITLE : =CONCAT fTITT-E , '-DATA'); 
(*Open With REWRITE since this Is a new file*) 
REWRITECF, TITLE); 

(^Remainder of program Is Identical to previous exa:m|ilg.*) 
Another useful example Is given below under WRITE and WRITELN. 



THE WRITE AND WRITELN PROCEDURES 

These procedutea may be uaed only on TEKT (FILE OF CUM) or INTERACTIVE 

files. They allow characters, strings^ and numeric values to be written 

to a file without Che need for explicit use of PUT or explicit reference 
to the window variable. Also, WRltBI+N allQhrs iJne-orJ ented output* The 

forms are 

WRITE t [ FILEID. ] ( ITEMS ] ) 
WniTELN ( ( I FILEID, ] ( ITEHs 1 ) ] 

where FILEID is the identifier of a TEXT or INTERACTIVE file which must 
be open. If the FU.EIO Is OTiJttedt OUTPCT Is assumed. 

IT£Ms means one or fDore iTEHs separated by coTmnas, Each ITEM has one of 

the following forms; 

EXPR 

EXPR I FIELDWIDTH 

Ot 
EXPR : FIELDWIDTH : FRACTIO^^LENGTH 

where EXPR is an expression whose value is to be written , FIELDWIBTH is 

an INTEGER expression which speci f ies the mjni Enum numiber of characters 
to be written, and PRACTIONLENGTH is ,an INTEGER expreaaion which 
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specifies Che number of digits Co be written after the decimal paint If 
EXPR is of type REAL- Hie default FRACTlONtENCTH is 5; the default 
FIF.LOWIDTH is I- For a nop-negacive IlEAL. value, one space is always 
written before th^ first digit; for a negative REAL value, the nrLnus 
sign occupies this poeltlon- 

WRITE evaluates the expressloriK and writes their values to the file In 
sequence. If EXPR ±3 of type CHAR, STRIHG, ot PACKED ARRAY of CHAR, 
WRITE writes the charscterts) to the file and Bdvsnces the file 
pointer. If a FIELDWTDITI has been given and the number of characters 
written Is less than specified, leiJding spaces are added to fill the 
field. 

If EXPR Is of a nufFierlc type, WRITE converts the value to a strini- ot 
characters in standard Pascal nuinerlc format* writes this string Co the 
file, and a,dvancefi the pointer- If the value is REAL and a 
FRAGTIONLEHGTli has been given, the specified number of digits are 
written after Che decimal point; if no FRACTION LENGTH is given» five 
decitnal places are written. If necessary, the value is rounded [not 
tmncaced) to the number of decimal places available. If 6 FIELDWIDTH 
has been given and the number of characters written Is less than 
specified, leading spaces are added Co fill tho: field* 

WRITELN works exactly like WRITE, except that after the last value has 
been written a return character is written to end the line. This allows 
line-oriented output with strlnR expressions. 

OUTPUT is the identifier of a predeclared INTERACTIVE file which can be 
used with WRITE and VRITELN. All characters written to OUTPUT are 
displayed on the console ecreen* When a progran is writing to OUTt'UT, 
the user inay type ctrl-S to stop the output- The pcogran halts until 
another character ts typed, then resumes the output where it left off. 
Also* the user may type ctrL-F. This halts the displaying of characters 
on the console screen, but the program continues to run* 

The following example program illustrates a number fif useful 
techniques* It uses line-oriented 1/0 with STRING variables, but 
performs character manipulations on the iiXHlNG variables. It also shows 
a useful trick for opening a file for output which may or may not cKist 
already. The effect of the profr.ram is to read the input file line by 
line, remove any leading periods frora the lines, and write the lineB out 
to the output file. 

PRDGRAH RUSHPERIODS; 

COWST PERIOD^'.'; 

VAR IHFILE, OUTKILE: TEXT; 

INNAllE, OUTNAME, LIKEBUF: STRING; 
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BEGIN 

C*Fit:6t get the files open-*) 
C*Get input filename'*) 

WRITECName of input file: '); 
READLN(INNAME); 
C*Siipply the default suffix .TEXT if needed.*) 

:f P0S('-\ INNAME)«=0 THKW i™AME:"COMCAT(INNA?re,'.TEXT'); 

(*Turn off autoTTiQtic error chacklng so program can do it.*) 

(*$!-*) 
(*ItLput file should already eicist, sd open with reaet.*) 

RESETdNFlLE, INfJAHE ) ; 
C*If It doesn't work, complain and stop program**) 

IF lOKESUlTog! THEN BEGIN 
WRITELNCFile not found.'); 
EXiT(PR0CRA?1) 

Em; 
(*Turn automatic error checking back on-*} 

(*$!+*) 

(*Get DUt|>ut filename**) 

WFITECNante of Mtput filer '); 

REAHLNCOUTKAME); 
(*Sopply default suffix .TEXT if needed**) 

IF POS('.', OUT^;AME)-(J THEN 0UT[;AME: =CONGAT{OUTNAME, *.TEXT')j 
(*OpEn file with rewrite.*) 

REWRITE COUTFlLE,OyTNAWE)i 

(*Wow do the Job-*) 

WHILE (HOT EOFaJJFILK)) AND (HOT EOF(OUTFILE) ) DO BEGIN 

REAl3LM(INFILF:,LrtJEBUF); 
IF LENGTH (LIKKBUF) >Q THEN 

IF POS(PERIOD, LIH£HUF) = 1 TliEN DELETECLIKEBUF, 1, 1); 

WRITELN (OUTFILE, LINEBtJF) 
EMU; 

(*Now clenn up-*) 

C*If the DutpLtt file ien*^t complete. ,, * J 

IF ECFfOUTFILE) THEN BEGIN 

URXTELN CNot enough room In output f ilel ' ) ; 
(****Then throw it away**) 

CLOSE [OUTFILK, PURGE) 
ENT 
C*If it's okay, than Irtck it into the directory.*) 
ELSE CLOSE(OUTFILE,LOCK.); 
CLOSE [INFILE) 
END. 
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THE PAGE PROCEDURE 

ThiG procedure sends a top-of-fonn character t^SCIl 12) to the file. 
The form is 

PAGE C FILEID ) 

where FILEID is the identifier of an open file of type TEXT or 
IMTERACTIVE. 



THE SEEK PROCEDURE 

This procedure allows the program to move a file pointer to any 
specified record in a file that ig not a textflle. This allows random 
scceas to file records- The form is 

EEFEC £ FILEID » AECNUM i 

where FILEID is the identifier of an open file that is not a 
textfileCl-e. not created with the .TEXT suffix), and RECNUM I3 an 
Integer value interpreted as a. record number in the flle- 

Thls procedure changes the file pointers so that the next GET or PUT 
from/to the fiU uses the record of FILEID specified by RECNUH. Records 
in files are nunibered from (J. A GET or PtUT UiuSt be executed between 
SEEK cslls since two SEEKS in a row may cause unexpected » unpredictable 
junk to be held in the window and associated buffers. Iiiiiriediately after 
a SEEK, EOF will return false; s following GET or PUT vill cbub* EOF to 
retiim the appropriate value. 

The following sample program dentonBtrates the use of SEEK to randomly 
access and update records in b file; 

PROGRAM RANPOKACCESSi 
{*Allows updat*? of any selected record In a file.*) 

vm 

RECNIMBER: INTEGER; 

FNAME: STRING; 
VITALS: FILE OF RECORD 

NAME: STRING [2ffli 

DAY^MONTItiVEAR: INTEOEE; 
ADDRESS: STRING (50] j 

ALl^^E: BOOLEAN 
END; 



N 
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BEGIN 
(*OhcAin Ellenanie.*) 

WRITECEnter filEnaine: '); 

READLN(FNAME); 
(*Use RESET to preaeir/e existing contents of file; but if it doesii't 
exist, use REWRITE to create it**) 

RESET (\T:TAL5, FMAHE)^ 

IF lORESULTofl THEN REWRITE (VITALS, FtiAME); 

( *$!+*) 

C*Repeat the following "forevarj" i.e* until EXIT is caused by user 
typing cCrl-C and caualng EOF<ISPUT). or by lack of diskette fipace for 
new record9.*J 

WHILE TRUE DO BEGIW 
{^Obtain record number; quit if user types ctrl-C, causing EOF.*) 
WRITE C 'Enter record number: '); 
READLN (RE.CKUMJ1ER) ; 
IF EOF THEN BEGIN 

CLOSE (VITALS, LOCK); 
EXIT (PROGRAM) 
END; 

(*GET Che specified record*) 

S EEK [VITALS , RECNUMBER ) j 
GET (VITALS); 

(*Up£iatG the regard*) 

WITH VITALS'" DO BEGIN 

URnELNfNAME); 

WRITE ('Enter correct nsme: '); 

READLN (MAME); 

WRlTELN<DAlf); 

WRITE ('Enter correct day: '); 

READLN (DAV ) ; 
(*..»and 30 forth with other fields of record.*) 
END; 

C*Mow SEEK the sane record agalni since the GET advanced the file 
pointer to the next record after It got the current record Into 
VITALS" *) 

SEEK (VITALS , RECHUMflER ) ; 

(*PUT updated record Into file; exit if this causes EOF**) 
PUT (VITALS); 
IF EOFCVITALS) THEM BEGIN 

HRITFXN('Not enough file apace!'); 
EXIT (PROGRAM) 
END 

Evm 

END. 



E 



THE UNITREAD AND UNITWRITE PROCEDURES 

THt.S£ ARE J3AKCERDL^S PKOCEPURF.S 

These aro the low-level procedures which do device-oriented I/O* The 

fcirns are 

DNITREAD ( UNITHUMIER, ARRAV , LEHr.TH [, (BLOCK^^J^[BEP] [, NODE]] ) 
UNITWRITE ( UNITKUNBER, AP.RAY, LENGTH (, {BLOCKfnJNBER] [, [MODE]] ) 

where; 

UKITNUMBEH, an Integer, la. the volume nuF.ber of an I/O 
device* The Apple Pascal Operating System Reference Kaniial 
describes these nutfibers- 

ARR AY Is the narae of a packed ar ray , wb i ch nay b e subs c r 1 p t ed 

to indicate a Starting position. This Is ueed ae the etarting 
address tn do the transfers from/to. A String may also- be 
used, but it should have a subscript ereater than 0, since the 
0th eleinent of a String contains data vhich usually shculd not 

be transnitted. 

LENGTH Is an integer value dcsignatinp the nur,iber of bytes to 
transfer. 

BLOCFl.'UilEERj an Integer, Is meaningful only when uplng a disk 
drive and la the absolute block number at which the tranefer 

xjlll start. Tf tlie PLOCKNL'prTiEB te left out, is asaumed, 

MODEj an integer in the range ().*I5^ is optional; the default 
is 0, It controls two UNITWRITF options which are described 
below. J*tlDE has no effect or. LINITP.FJ^D. 

The UNITWRITE options controlled by the NODE parameter apply only to y 
text-orlentod l/o devices such as the console or a printers they do nOi£ 
apply to diskette drives- Both opt lone are enabled by default, if no 
MODE parameter Ifi supplied. 

One option ia conversion of DIE codes." In a Pascal textflle, any 
leading spaces at the beginning of b line are represented by a CLE 
character (ASCII 16) followed by a code value which Is 32 plus the 
number of spaces. On output to & non-block-structured device such ss a 

printer, the DIE com'ersion option detects the DhF code and converts it 
Into a sequence of spaces - 

Conversion of DLF cndes Is dlsablec^ by a MODE value thnt bas 9 one in 
Pit 2 (see below). 

The other option Is automatic line feeds. In a Pascal textfile, the end 
of each line is marked by the end-of-llne character CR (ASCII 13) 
without any line-feed character. On output to a non-blocV;-8tructured 
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device such as a printer, the autam^tlc line-feed option Inserts an LF 
character (ASCII 1(1) after every CR character (ASCII 13). 

AutopJatlc line feeds are dlsaliled by a MODE value that has a one in 
Bit 2 (see b^low). 

Only Bit 1 and Bit Z ol' tlie MODE value have any signlf leanco , Bit 2, by 
itaelf, correeponds to a value of 4, and Bit 3 by Itself corresponda to 
a value of 8. The followlnfi values can be used to control the options: 

- MODE-^i fche default value) caueea both options to be enabled, 

* MODE'^i causes automatic line feeds to be dleabledt while 
leaving DLE coirveralon enabled. 

- Mnnr^8 causes DLE converelori to be disabled, while leaving 
automatic line feeds enabled' 

- MODE^IZ disables toth PLF. conversion and automatic line 

feeds. 



THE UNITBUSY FUNCTION 

This l9 a UCSD Pascal procedure uaed to Indicate whether a specified 
device la busy. But since the T/0 drivers nn the Apple are not 
Interrupt driven, UNITBUSV will always return the value FALSE. To test 
whether a character Is available from the Apple keyboard, use the 
KEYPRESS function (see Chapter 7). 



THE UNITWAIT PROCEDURE 

This Is a UCSU Pascal procedure which vaits for a specified device to 
complete the I/Q in progress- But since the I/O drivers on the Apple 

are not Interrupt driven, UKITU^AIT does nothing. 
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THE UNITCLEAR PROCEDURE 

This procedure cancels all I/O operations to the specified unit and 
resets the hardware to Its power-up state- The form Is 

[JNITCLEAR < UKITNUMBER ) 

lORRSULT is set to a non-zero value if the specified unit is not present 
<you can use this to test whether or not a given device is present In 
the systen). The fona 

DNlTCtEAR (1) 

flushes the type-ahead buffer for CONSOLE; and resets horizontal 
scrolUng to full left (displays leftmost AQ characters on Apple's 
screen). 



THE BLOCKREAD AND BLOCKWRITE FUNCTIONS 

These functions transfer data to or frcrn an untyped file* They return 
an integer value wlilch is the number of blocks of data actually 
transferred. The forms are 

BLOCKREAU ( FILEID, ARRAYNAHF-» BLOCKS [, RELELOCKl ) 
BT,0CKWR1T£ ( FILEID. ARRAY?Ji«^» BLOCKS [, RELBLOCK] ) 



where 



FILEID muat be the identifier of a prevloualy declared untyped 

file. 

AURAYHAME is the identlflet of a previously declared array. 
The length of the array should be an Integer nEjltiple of 512, 
ARRAYNAME nay be Indexed to indicate a starting position In 
the array. 

BLOCKS is the number of blocks to be transferred. 

RELBLOCK is Che block number relative to the start of the 
flle» the sero-th block being the first block In the file. If 
no RELBLOCK Is Specified, the readg/writes will be done 
sequentially* Specifying RELBLOCK moves the file pointer* 



HARMING; Caution should be exercised when using these functions, aa the 

array bounds ate not heeded. EOF (KILEIP) becomes true iiAien the last 
block In a file la read* 
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The following program illustrates the use o£ BLOCKitEAQ and BLOCKWRllE. 
PROGRAM FILED EMO; 

VAH 

BLOCKIIUMBER, BLOCKS THAKSFEKR ED : INTEGER ; 
BAD 10: BOGLIJj;; 
C^Fs FILEj 

buffer; FACKEH ARRA¥[fl.,5n] OF chak; 

{* This program reads a diskflle called 'SOURCE* DATA' and copies 
the file into another dlfikflle called 'DESTINATION' ueing untyped 
files and the built-lns ELOCKREAD and BLOCJCWRITE *) 

BEGIN 

BADIO:=FALSE; 

RESEKG/SOUHCE-DATA") J 
REWRITE (F, 'DESTINATION ' ) ; 
BLOCKlit[MBER:=ff; 

BLOCKSTRANSFERRED; ^BL&CKftEAD (G , BUFFER^ I ^ BLOCKNUMBER ) ; 
WllLl- (NOT ECiF(G)) AKB flORESULT-fl) AMD (NOT BADXO ) ANB 
{BtOCKSTRANSFERRED=l> DO 
BEGIN 

BLOCtCSTRAWSFERRKTl : =BL0CK1JRITE CE , BUFFER , 1 , RLOCKJrUHBER ) ; 
BAD:0:i^(fB].OCKSTRANSFERREn<:i) OR (lOFiESULTOfl) ) ; 
BLOCEiNlfMRER;=BLDC^aT[?^tBER+l i 

BLOCKSTRAWSFERRED; -BLOCKREAD(G, BUFFER, I, BLOC KNWIEER) 
END J 
CLOSE {F, LOCK) 
EWD. 
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MISCELLANEOUS BUILMNS 



THE ATAN FUNCTION 

The ATAN function Is simply a different identifier for the ARCTAN 
function of Standard E'aacal, Along with the otKer transcett dental 
functionB, It is part of the TRAKSCENO UMIT supplied! with Apple Pascal 
(see Chapter 7} * 



THE LOG FUNCTION 



The 



This function returna a. real value which is the logarithm (base 1'^) of 
ItB argument. Alung with the ocher transcendental functions, It Is part 
of Che TRAilSCEND UNIT supplied with Apple Pascal (see Chapter 7). 
foriD is 

LOG ( NUMHER ) 
where NLIMBER can be either a real oi an integer value. 



THE TRUNC FUNCTION 



ThD function TRUNC will accept A LONG INTEGER as well as a REAL as an 
argument, t>verflow will result If the absolute value of the argument 
exceeds MAXINT* With a REAL arguiTient » TRUNC returns an IHTECiER value 
formed by dropping the fractional part of the REAL value. With a LONG 
INTEGER value, TRUNC returns a numerically equivalent INTEGER value* 



THE PWROFTEN FUNCTION 

This functiott retuma a r&al value which is 10 ta a s:pecifled (integer) 

power. The form is 

PWROFTEN ( EXPONENT ) 

where EXPONENT Is an Integer value In the range j|..37. This function 
returns the value of L0 Co Che EXFOHEWT power- 
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THE MARK AND RELEASE PROCEDURES 

The Standard Pascal pcocedure DISPOSE is not provided In Apple Paacijl* 
Instead r the MARt and RELEASE procedutes are used for returning dynamic 

metnary allocations to the system- The forms are 

MARK ( HEAPPTE ) 
RELEASE ( HEAPPTR ) 

vhere EEAPPTR is of type "INTEGER and is called by reference in the HARK 
procedure. MARK sets HEAPPTR to the value of the syatem's current 
top-of-heap pointer* REiLIlASE sets the syatein'e top-of^eap pointer Co 
the value of IIHAPFTR. 

The process of recpvering memory space described below Is only an 
approxiinatlon to the function of DISPOSE as one cannot explicitly aak 
that the storage occupied by one particular variable be released by the 
system for other usee. 

Varlablea created by the standard procedure WEV; are stored In a stack- 
like structure called the "heap". The following program is a simple 
demonstration of how HARK and RELEASE can be used to chanpe the size of 
the heap* 

?ROCKAM SMALLHEAPf 

TYPE PERSON^ 
RECORD 

HA>IE: PACKED ARRAY [(J. . 15] OH CMR; 
ID: INTEGER 

END; 

VAR F: '■PERSON; 

REAP: "INTEGER; 

BEGIN 

HARK(HEAP); 

NEWfP); 

P".NAME:"'FARKLE, KENRT J» ' ; 

P-,ID;- 999; 

RELEASE CHEAP) 

The program shows a particularly handy method for deliberately accesaing 
the contents cf memory which is otherwise inat:ccssabl<^* It first calla 

HARK to place the address of the current top of heap into the variable 
HEAP. 
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Below la a pictorial description of the heap gt this point In the 
prograiD''e execution : 



TOP OF HEAP —> 



HEAP 



C0[i[:enEs of heap at 
start Qf program 



Next the program calls the standard procedure NEW and thia rcsulta in a 
new variable P'^ which Is located in the heap as shown in the diagran 

below; 

rOP OF HEAP > I 1 



contents of heap at 

Btart of pEog,ra,m 



<i HEAP 



After the RELEASE the heap is as follows: 

TOP OF HEAP > I 



concents of heap at 
Btart of progrsTTi 



I <-^ 



HEAP 



I 



Once the proe;rain no longer needs the variable P"" and wisheEJ to "release" 
this mcjiory apace to the systeci for other uses, it calls RELEASb: ^rfilch 
resets the top of heap to the address contained in the variable HEAT* 

If tfElJ had been called several times between the calls to llAHK and 
RELEASE, the sitorage occupied by several variables would have been 
RELEASEd at once* Note that bRcause of the stack nature of the heap it 
is not possible to release the Tueniory spac€ used by a single item in the 
middle of the heap. 



OP 



Careless use of MARK and RELEASE can leave "danEllng p(iinters*\ pointin|i 
ta areaa of menory which are no longer part of the defined heap space. 
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THE HALT PROCEDURE 

This procedure generates a HALT opcode thoL, \rtien executed^ causes a 
non^f atal run ~ time error to occur* The form Ifl 

HALT 

For a more orderly way to tertninate program execution, see EXIT below. 



THE EXIT PROCEDURE 

The EXIT p^riDcedure causea an orderly exit froo & procedure or funetlonj 

or from the program itself. The fanos are 

EXITfprocedurenanie) 
EXI T (progranname ) 
EXITCPROGIUH) 

In the ElrsE form shown, ESIT accepts as Its single paraineter the 
identifier of a procedure or function, to be exited* Note that this need 
not be the procedure or function in which the EXIT atatenent occurs* 
EXIT foLLows the trail of procedure or function calls back to the 
procedure or fiinctlon speclflied; each procedure or funccioii In the trail 
iB exited. If the specified procedure is recursive, the looat recent 
invocation of that procedure will be exited* 

When a procedure or functlnn ia exited via EXIT» any files local to It 
are automatically closed, just as if it had terminated normally. 

The use oE EXIT to exit a function can cause the function to return an 
undefined value if no aeslgnment to the function identifier ts made 
before EXIT is eKecuCed- 

When the prograni name or the reser\/ed word PROGRAM la used as the 
parameter for EXIT, EXIT brings the program to an orderly halt* 



THE MEMAVAIL FUNCTION 

This function returns the number of words currently between the top^ef- 

etack and top-of-heap. This can be laterpreted as the ainount of memory 
available at that tliae. The form la 

MeiAVAIL 
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THE GOTOXY PROCEDURE 

This procedure sends the cursor to a specified position on the screen* 
The form i.m 

GOTOXY ( XiCOORD , YCOORD ) 

where XCOORD and YCOORD are integer values interpreted a& X (horizontal) 

and Y (vertical) coordinates. XCOORB mist he in the range ^? through 79; 

YCOOtlD must be In the range ^ through 23. The cureor la sent to these 

coordinates* The upper left corner of the screen is assunied to he 
(fl,t*). 

This procedure is written to work with the ^ple IT's screen- Ef you 
wish to use an external terminal, you will need to bind in a new GOTOXY 
using the BINDER package described In the Paacal Operating Systeai 
Manual* 



THE TREESEARCH FUNCTION 

This a fast function for searching a binary tree that has a particular 
kind qf structure* The form la 

TH£ESEARCH(ROOTPTR, NODEPTH, NAME J 

where ROOTPTR 13 a pointer to the root node of the tree to be searched, 
NOEEFTR is a pointer variable to be updated by TRKESEARCH, and NAJTE is 
the Identifier of a PACKED ARRAY [l.-SJ OF CHAR which contains the 
fl— character name to be searched for in the tree. 

The nodes of the binary tree are assumed to he linked records of the 
form 

KODE-RECORD 

NAWE: packed ARRAY[I..8] OF CHAR; 

LEFTLINK, RIGHTLINKi "NODE; 



**,(*other fields can be anything*)- 



END; 



The type name and the Held names are not important; TREESEARCH only 
assutnea that the first elj^ht bytes of the record contain an &-cha.racter 

nane and are followed by two pointers to other nodcE. 

It is also assumed that names are not duplicated within the tree and are 
assigned to nodes according to an alphabetical rule; for a given nodej 
the name of the left subnodn la alphabetically less than the name of the 
node, and the name of the right subnode is alphabetically greater than 
the name of the node. Finally* any links that do not point to other 
nodes should be NIL. 
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TREESEARCH can return any of three values : 

U: The NAME passed to TREESEARCH has been found In the tr&e- 
NODEPTR now points to the node with the specified name. 

1; The NAME is not in the tree- If it i& added to the tree, 
it should be the right subnode of the node pointed to by 
NODEPTR , 

-1; The NAHE is not In the tree. If it is added to the tree, 
it fihauld be the left subnode of the node pointed to by 

MODEPTR* 

The TREESEARCH function does not perform any type checking on the 
parameters parsed to it* 
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BYTE-ORIENTED BUILT-INS 



These procedures and functions are all hy te-oriented. The systcns does 
not protect Itself from thetti, as no range checking of any sort ia 
performed on the parameters and no type checking ia performed on Che 
source and destination pararaetera. Read the descriptlonB carefully 
before trying them out. Also, some Tiachine dependencies may lurk In the 
Implenefitacions. 



THE SfZEOF FUNCTION 

This function returns an integer value, which is the number of bytes 
occupied by a epeclfted variable, or by any variable of a specified 
type- SIZEOF Is particularly useful for FILIJ^HAR, HOVEIilGHX, and 
HOVELEFT built-ins (see below). The form Is 

SIZEOF ( IDENTIFIER ) 

where IDENTIFIER 1e either a type Identifier or a variable identifier. 



THE SCAN FUNCTION 

This function scans a range of ineraory bytes, looking", for a one- 
character target* The target can be a specified character, or it cen be 
any character that dloee not natch the specified character- SCAN returns 
an integer value, which is the number of bytes scanned. The form is 



SHAN { LIMIT , PEXPR , SOURCE ) 



where 



LIMIT Is an Integer value which gives the maxlinum: nuinhGr of 

bytes to scan- If LIMIT is negative, SCAK wl.H scan backward. 
If SCAN falls to find the specified target, it will return the 
value of LIMIT* 

PEXPF is a "partial expression" which specifies the target of 
the scan. PEXPR takes one of the following forms: 



- CK 
<> CH 



(target Is a character equal to CH) 
(target is a charactec not equal to CH) 



where CH stands for any cKpcesslotl that yields a result of 

type char. 



BUILT-IN PROCEDURES AND FUNCTIONS 51 



SOURCE Is s variable of any type except & file typn. The 
first byte of the variable is the 3tartliig point of the acaii- 

SCAtf teriDitifltts when it fluds the target or wheu it has scaLuied LIMIT 
byttis. It theti returns the uufciber of bytes BcaiiLied> If the target is 
found at tile starting poiiitj the value teturiied will be zero. If LIMIT 
Is negative, the scan will go backward and the value returned will alao 

be negative- 

Exanples: Suppose that DEM Is declared as follows: 

VAP DKH; PACKED ARRAV [|5,*l0f)] OF CHAR; 
and then the first 53 elemeuta of DEM are Idaded with the characters 

THE PTERO IS A HEMRER OF THE, PTERDDACTYL FAt«L¥, 

Me then have the fDllowliig: 

SCAMC-26, = ':\DEMt30] ) will i-*?turit -lb 

SCAHC100,<>'.%DEH> vtll return 5 

SCANflS,^' \DEM[5|) will return 3- 

THE MOVELER AND MOVERIGHT PROCEDURES 

Thes^ procedure:} do rnaBS iiDVes of a specified Liun^er of b^tes. The 

forms are 

MaVFI,FFT ( SOURCE , DESTINATIOR , COUNT > 
ilOVERIGHT ( SOURCE , CESTISATION , COWT ) 

uhere SOURCE aud DESTINATION are Cwd variables c( any type except a file 
type. The first byte of SOURCE Is the hegiiniliig of the rouge of bytes 
whose values are copied. The first byte of DESTTHATTON Is the begliiuliig 
of the rauge of hyt^s Chat the values are copied Into. COUNT Is an 
Integer and Rpecifles the juimber nf bytes moved. 

MOVELEPT starts from the left end nf the SOL'RCE range. It proceerls frtia 
left tn risht, copylug bytes Into UESTISATION, starcliig at the left end 
□ f the DESTINATIO!) range. 

MOVERir.HT starts froto the rJ(>hc end of the 50UFCE range. It proceeds 

from rlRht to left, r-npyiilR liytesa luto DESTIMATIOK, starting at tbe 
right aixd of the DESTINATION range. 

The ressBii for having both nf these la that the SOURCE and DESTINATION 
ranges may o^ierlap. If they tr/erlap, the order In which bytes are mcved 
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Ifl trltical: each byte must be moved before it gets overwrittEu hy 
another byte* 

Iji general this consideration applies when SOURCE and DESTINATrON are 
subarraya of the sane PACKED ARRAY OF CHAR. If bytes are being moved to 
the right (DESTITJATION has a higher subscript thau SOUKCE), use 
MOVERIGHT* If bytes ^re being moved to the left tDESTINATlON has a 
lower ^subscript than SOURCE) , use MOVFILEFT* 



THE FILLCHAR PROCEDURE 

Thla procedure filla a specified range of meEoory bytes with a specified 
character value* The form Is 

FILICHAB C DESTINATION , COUNT , CHARACTER ] 

where DESTINATION is a variable of any type except a file type- The 
first byte of DESTINATION la the begiiini.ng of the range of bytes ta be 
filled, COUNT Is an Intesei: value ajid apecifiea the number of bytes to 
be filled. CHARACTER is a chatacter value to be copied into each byte 
ill the specified range- 
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SUMMARY 



STRING BUILT-INS 

Integer-Valued Functions: 

LENGTH ( STRG ) returns lengtb of string. 

PCS { SUBSTRG , STRG ) returnjg Index of first 
occurence of SUBSTRG i^thln STRG, 

String-Valued Functions: 

CONCAT £ STRGa ) returns concatenation of strings^ 
COFV ( STRC , INDEX , COUNT ) returns a BubBtrlng 

of STRG> 

Procedures: 

DELETE ( STRG , INDEX ^ COUNT ) deletes a BubBtrlne 

of STRG. 
INSeat C SUBSTRG , SritG , XNQEX 3 inserts a substring 

into STRG, 
STH ( LONG J STRG ) converts intEgGr or long integer to 

string of decimal dig! ts - 



INPUT AND OUTPUT BUILT-INS 

Opening and Clloslng Files: 

RESET ( FILEID [, TITLE] ) opeflB exiotlng diskette file, 

or resets pointers to beginning if alrsady open- 
REWRITE { FXLEID , TITLE ) opens new diskette file, 
CLOSE C FILEID [, OPTION] ) closes File- OFTlON may be 
LOCK, NORMAL, PURGE, or CRUCJCH. Default is NORMAL, 

File Pointer Status: 

EOF (< FILEID )] booleafii crue if end of file has been reached 
or file is closed. Default FILEID Is INPUT. 

EOLK t< FILEID )] boolean, true If end of line haa been reached- 
Default FILFin is INFUT, 

SEEK C FILEID , INTEGER J moves file pointer to specif led 
record. 



I 
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Typed File l/O: 

GET f FiLitD ) reads current file record Into window 6 advanceg 

file pointer. Default FILEID Is INPUT. 
PUT C FILELD ) writes window Into current f J le record i advances 

file pointer. Default FILEID Is OUTPUT* 
lORESULT returns an Integer value which dopendfi on status of 

most recent 1/0 operation. Value la zero for OK completion* 
READ ( [FIL£ID|] VBLs ) where VBLs means one or mere variables 

separated by coMnas. Successive values are rt^ad from file 

into variables. Default FILEID is INPUT, FILEID muBt be 

of type TEXT (FILE OF GUAR) or IHTERAGTIVtl, 
READLN ( (FILEID J VBLs i Like READ, but skips to beginning 

of next line after reading value for last VBL. 
WRITE ( [FILEID, ] [ EXPRs 1 ) where EXFRs means one or more 

expressions separated by cocmiiaa. Each CXPR niay also be 

followed by field width and nunnber of deciioal places* 

Expression values are written to successive file records. 

Default FILEID Is OUTPUT. FILEID muat be of type TEXT 

(FILE OF CHAR) or INTERACTIVE, 
WRITELN I ( [KILEIDJ [ EXPRg J ) I Like WRITE, but writes en 

end-of-line after last EXPR valuer 
PAGE ( FILEID ) writes a top-of-forra fASCII 12>. 

Device I/O: 

These built-ina are deacrlbcd in detail in the text. 

UNITREAD ( UNITNUMBER , ARRAT , LENCTti [, [BLOCKNUMBER] [, HDDEH ) 

UNITVmiTE ( UNITNUMflER , ARRAY , LENGTH [, [BLOCKNUMBERf [, MODE] I > 
UNITBUSY ( UtilTNUMBER ) : BOOLEAN 
UNITWAIT C UHITNUHBER ) 

UNITCLEAR ( UNITNUMBER ) 

Untyped File I/Oi 

These bullt-ins are described in dotall in the text. 

BLOCKREAD {FILEID, ARRAY, BLOCKS [j RELBLOCKJ ) 1 INTEGER 

BLOLIKWRITE (FILEID, ARRAY, BLOCKS [, KELaLOCKH : INTEGER 
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MISCELLANEOUS BUILT-INS 

ATAN { NUMBER ) returna a REAL value- This ia the ARCTAN 

function of Standard Faecal. NUMBER niay be REAL or 

IKTEGER, 
LOG ( NUMBER ) te turns a REAL value » the log base 11? of 

NIMBRR, NUMBER may be REAL or INTEGER. 
TttUHC ( NUMBER ) returnfl an INTEGER value. This is like 

Standard Pascal except that NimflER may be LONG INTEGER 

instead of REAL- NUMBER may not exceed MAXINT. 
PWROFTEN ( EXPOHEWr ) returns a REAL value which ie 

Ifl to the EXPONENT power. EXPONENT is an INTEGER In the 

range (J* * 37. 
HARK ( HEAPPTR ) where HEAPFTR is qf type n:NTEGER. HEAPPTR 

is called by name and la aet to current top"of-heap« 
RELEASE ( HEAPPTR ) where HEAPPTR is of type n:NTECER-. The 

current top-of-heap pointer is set to HEAPPTR. 
KALT causes non^fatal nin-tiine ettor; halts program. 
EXIT causf^s orderly exit Eroni procedure, function, or 

program. 
MEMAVAIL returns an INTEGER value, the ntitaber of words between 

top-of-stack and top-of-heap. 
GOTOXY C XCOORD , YCOORU ) moves ecreen cucspr to specified 

coordinates. XCOORD is an INTEGER In the ran^e 0, , 79 and 

YCOORD la en INTEGER in the range 3.*23, 
TREESEAKCH ( ROOTPTR , NODEPTR , KAHE ) searches for NAME in 

a binary tree* See text for details. 



BYTE-ORIENTED BUILT-INS 

^eee bullt-ina are described In detail in the testt. 

SHEOF ( VARUBLE OR TYPE IDENTIFIER ) 

SCAN ( LIMIT , PEXPR , SOURCE ) 
KOVELEFT ( SOURCE , DESTINATION , COUNT } 
HOVERIGHT ( SOURCE , DESTINATIOK , COUNT > 
riLLCHAR [ DESTINATION , COUNT , CHARACTER J 
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INTRODUCTION 



fe 



The purpose of the Apple Paecal Compiler Js to translate the texc of a 
Pascal program Into Ehe compressed P-co4e version of the program. This 
P-eode is Che 'Wchine laneuage" of the UCSD Paacal interpreter or 
"pseudo-machine." described In the Apple Pascal Operaclng System 
Manual- 
Complete details en operation of Che Compiler are in the Pascal 
Operating System Reference ManuaU the fqllowing two aectlons oa 
diskette files needed and on using the Compiler are somewhat abridged* 



DISKEHE FILES NEEDED 



Ta operate the Pascal Compiler* you need the following diakecte file 



Textflle to be 
CcDipiled 

SYSTEM. COMPILER 
SYSTEM. LIBRARY 



Other Libraries 



SYSTEM, EDITOR 



SYSTEM* SYNTAX 



(Any diskette, any driven defatflt 
is boot diskette's text uorkfile 
SYSTEH<tfRK.TEXT, any drive) 

(Any diskette, any drive) 

(Boot diskette, any drive; required 
only if any of the UNITg in the 
system library are USEd by the 
program. See Chapter 5.) 

(Any diskette, any drive; required if 
any UNlTs not In the system library 
are USEd by the program being, 
compiled. See Chapter 5. ) 

(Any diskette^ any drive J optional: 
to flit errors found by Compiler) 

(Boot dlsketceit any drive; optional 
ciessages given on entering Editor) 



I 






In addition to the above files, the following files may be needed if you 
are invoking the Compiler automatically via the R(un command (see Apple 
Pascal Operating Systeto Reference Manual for details): 

SYSTEfi,LIMKER 
SYSTEM. PASCAL 

SYSTEM.CIIARSET 

One-drive note: The files SYSTEM, COMPILER, SYSTEM-EClTDRj and 
SYST&i, SYNTAX are all on diskette APPLET*:, ^^ich Is the normal one- 
drive boot diskette. If you have been working on a program In the 
EditDr, and U(pdatlng the workflle, your boot diskette baa all the files 
needed Co R(un or CComplle the workflle- If you wish to Jl(un or 
C(ompile a. textfile that Is not already on the boot diskette,, use the 



m ■ ^ 

*i ^ 

■ j ^ 

■ ^ 

■ j 4 
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Filer's T{ransfer conunaiid to transfer that textfile onto your boot 

disketCE before compiling. If your program requires LlnkiuR to external 
foatlnes, see the Apple Pascal Operating System Manual. 

Hulci-drive note; The files SYSTEM^EDITOR and SYSTEM. SYNTAX are both on 
diskette APPLEL:, which Is the normal tnultt-drive boot diskette. The 
file SYSTEM. COMPILER is on diskette APFLE2: , which is normally kept In 
drive volume i^b: in a nulcl-drlve systen. With APPLEl; In the boot 
drive and APPLE2; in a non-boot drive, your eyateia has all the files 
needed to R(un or C(oraplle the vorkfile- 

Two-drive note: If you wish to R(un or C(oTHplle a textflle that Is not 

already on APPLEl: or APPLE2:, and your aystem has only two drives, use 
the Filet's Tfransfer cominand to transfer that textfile onto either 
APPLEl; or APPLE2; before compiling. Another possibility for two-drive 
systems is to rnake APPLE0: your boot diskette (just put APPI.E0: In the 
boot drive and press the Apple's RESET key). This frees your second 
drive to hold a source or destlnaclon diskette for compilations, saving 
you from T (ransf erring the source file onto APPLEl: or APPLE 2: . APPLE?: 
does not contain SYSTEM, LINKER; if your program requires Linking to 
■external routines, use APPLEl: and APPLE2: . 



USING THE COMPILER 



The Coropllef Is. Invoked by typing C for c:(onpilG or R for E(un from the 
outermost Command level of the Pascal system* The screen iramediately 
shows the message 

COKPILINC*. 

The Compiler automatically compiles the ,TEKT part of the workfile and 
saves the resulting code (if compilation is successful) as the •CODE 
pare of the workfile- If there is a workflle, but you do not wish to 
compile that file, use the Filer's Nfew command to clear away the 
workflle before compiling. If no workfile Is aveilabLe» you are 
prompted for a source filename; 

COMPILE WHAT TEXT? 

You Should respond by typing the naeoe of the text file that you wish to 
have compiled. Do NOT type the suffix .TEXT — that suffix is 
autotnatlcally supplied by the Compiler, in addition to any suffix you 
may specify^ 

Next, if there is no workflle, you will be asked for the name of the 
file where you wish Lo eave the compiled version cif your program: 

TO WHAT CODEFILE? 

If you simply press the RETUB.N key the coumiand will not be terminated, 
as you might expect. Instead, the source file will be compiled and the 
compiled version of your program will be saved nn the boot diskette's 
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worfcflle SYSTIM.VRR.CODE. This is handy if you then wish co R(un the 

program. 

If you want the compiled version of your program to have Che sauiE name 

as the text version of your prograrti (df course, the suffix will be *CODE 
Instead of .TEKT), juat type a dollar sign and press the RETURK key. 
This Is a handy fgature, since yon will usually vant to remember only 
one name for both versions of your program. The dollat sign repeacs 
your entire source file .specification, Including Che -volurae IdentlflEr 
BO do NOT specify the volume Identifier before typing the dollar sign/ 
Note that this use la different from the use of the dollar sign in the 
Filer. 

If you want your progratn stored under another filename, type the desired 
filettame. Do NOT type the suffix -CODE -- that aufflx is mutoiDfltlcally 
supplied by the Compiler, In addition to any atiffix you may specify. 

By default, the compiler places the code file at the beglnnltif of the 
largest unused space or the diskette* To override this, yau can give a 
size specif ication with the fllenaaie. In this case, you DO type the 
aufflx .CODE, followed by the nujnber of blocks in square brackets, 
followed by a period; 

TO WHAT CODEFILE? HYPKOG . CODE I a K 

The period at the end prevents the system from adding the *CODE prefix 
after the size spectf icatlon- The size specification [B] causes the 
code file Co be placed In the first location on the diskette where at 
least 8 blocks are available. 

While the compiler is runnlngi taesssges on the screen show the progress 
of the corapilatldn as In the following exaiople; 

PASCAL COMPIUER II. i [B2B1 

TUNAFISH I Z33A WORDS) 
<; t> 

U LirTES 

SMALLEST AVAILABLE SPACE " 233^ WOBDS 

The IdentifleTB appearing on the ecreen are the identifiers of the 
program and Its procedures* The Identifier for a procedure is displayed 
at the tiontent when compilfltlon of the procedure body is started* 

The numbera within { ] indicate the number of (15-Mt) words available 
for symbol table storaie at that point In the compilation. If this 
number ever falls below 550, the compiler will fall. You must then put 
the swapping option (described below} Into your program and recompile* 

The numbers enclosed within < > are the current line numbers, 
on the screen represents one source line compiled. 



Each dot 



If the Compiler detects an error In your program, the screen will show 
Che text preceding the error, an error nurriber, and a marker «« 
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pointing to Che symbol In the source where the error waB detected, 
following is an exaraplei 



The 



( «« 

LINE 9, ERROR 18: <SP> fCONTINUE) , 



<ESC>C TERMINATE 3, E(DIT 



Thla shows that the bracket [ is an Illegal syiDbol at this point in the 
program* You have three options when you see a message like thla- 
Pressing the spacebar instructs the Compiler to continue the 
con^llatlon, in case you want to find more of the errora right now* 
Pressing the ESC key causes termination of the compilation and return to 
Che Connmand level. 

Typlag E sends you to the Editor, which automatically reads In the 
workflle. ready for editing* If you were not compiling the workfjie, 
the Editor requests the name of the file you were conipiling* Ydu should 
respond by typing the filename of the file you were cotnpi ling, and that 
file will then be read Into the Editor. When the correct file haa been 
read Into the Editor, the top line of the screen displays the error 
message (or number, if SYSTEM* SYNT AS wss not available) and the cursor 
is placed at the symbol where the error was detacted- 

If SYSTEM. SYNTAX Is not available, you can look up the error in Table 6 
of Appendix B, (You may wish to delete the file SYSTEM*SYNTAX to obtain 
more diskette space.) 



THE COMPILER OPTIONS 



COMPILER OPTION SYNTAX 

CoE^jller options (see the following section for details) are placed in 
Che text to be compiled, and take effect when the Compiler arrives at 

the option during compilation* 

Compiler options look like a special kind of comment, and take the 
following form: 

(*$option*) 

The Co^s^3lle^ treats material between (*S and *) as a compiler option* 
As shown below, there oust be no spaces in (*? or lumiediately after the 
S character: 



(* $G-*> 
(*$ G-*) 



This is a coitq>ller option- 
This is a comment. 
Thia is a coTxnent*^ 
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Several options can be combined In one set of t*5'*.*) brackets, by 
separating the options with corantas (don't add extra spaces): 



(*5optlor:,optJoTi*) 



Example: 



[*$I-,.S+,G-*) 



You can't do this with the options that involve nacies or scriogs of 
characters > 

A given option nay be turned on or olE at any point in Che compilation. 
The compilation is affected only from the point where the option is 
turned on until the point where the option is turned off again. Thus 
you can turn an option on (or off) Juat during the coniplUtlon of a 
particular routl n& in your program' 

Sorae options require a filenatae iMDediateiy fDlIowing the option letter, 
Instead of the usual + or -. In this case, all charactera between the 
option letter and the closing *) are taken ae the fllGnarae, except that 
blianks preceding or following the fllenarae are Ignored- Therefore, the 
illenatqe mst be the last item before the *) . If the fJrst character of 
a filename is + or -, you mist place a blank between the option letter 
and the fUenane, For examples of specifying a filename, see the 
aection dG3crIbing the Include-file mGchanlsm, 



In Apple Pascal, curly brackets { and } are equivalent to the normal 
cooinent or option deUniiters (* and *J , The curly brackets cannot be 
generated by the Apple keyboard, so no confttgion exists for programa 
written on the Apple computer. However, other terminals may be able to 
generate the curly brackets in programs. These programs will be 
execuced correctly an tKe Apple, but the curly brackets will be 
displayed on Apple's scrtjen as sc|uare bracketB [ and J . 



THE "COMMENT" OPTION 

This option tonsists uf the letter C end a line of text. The text Is 
placed » character for character, in Block of the codefile (where it 
will not affect prograiEi operation). The purpose of this is to allow a 
copyright notice or other conament to be esLbedded in the codefile, 
ExaiDp le : 

(*$C COPYRIGHT ALLUVIAL 0. FAWSOME I97g*) 

The CoEnutfut option uwst precede the heading atateiftent of the program. 
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THE "GOTO STATEMENTS" OPTION 



Tells the ComplleT whether Co allow or forbid the use of the Pascal GOTO 

Btatonert within a program. 

Default value: G~ 

(*$G+*) AllouE the use of Che GOTO statement. 

(*$G_*) Causee Che Compiler to treat a GOTO as Btl error. 

Teachers sDniecimes use the G- option to keep nD\.'lce programmers from 
using the GOTO statemerit where more structured approaclies using FOR, 
WHILE, or REPEAT Htaceraents would be more appropriate. 



THE "lO CHECK" OPTION 



This option tells the compiler whether or not to create error-checkinfi 
code after each structured file 1/0 statement (not the BLOCK or UNIT I/O 
statements). 

Pefault value; 1+ 

(*$!+*) Instructs the Conpller to generate code after each 

Btat&ffient which performs any I/Oj In order to check 

that the 1/0 operation was accomplished successfully. 

In the case of an unanccessf ul I/O operation, the 
program will be termtnated with a run^-time error. 

(*S1-*) Instructs the Compiler not to generate any I/O- 

checking code* In the case of an unsuccessful I/O 
operation, the program is not terainated with a run- 
tiiiie error. 

The <*$!-*} option is useful for proerams where I/O checking is not 
desirable, or which do their own checkinE via the lORESULT function. 
The prograni can then detect and report the I/O errors, without being 
terminated abnormally with a run-time error* However, the disadvantage 
of Getting the {*$!-*) option is that 1/0 errors, (and possibly severe 
program buga)^ may go undetected. 



THE "INCLUDE FILE" OPTION 

The Eyntax for Instructing the Compiler to Include another source file 
into the compilation is as follows: 

(*S1 filenanie *) 

All characters between (*$1 and *) are taken as the filenam'e of the 
source file to be included. Thus, the filename must be the last item 
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before the *). 
igncred* 



aces preceding Che filename and following It are 



Note that If the first character of a filename 1b + or -, you MUST place 
a blsnk space between (*$! and the filename. Also, you may not use the 
* or *r notation In the filename tc specify the boot diskette. 

If the Initial attempt to open the file which Is being included (also 
called the "include file") fails, the Compiler concatenates the suffix 
.TEXT CO the fllenathe and Cries again- If chle second attempt falls, or 
if flome I/O error occurs while reading che Include file, the Compiler 
reaponda with a fataj error tneasage and terminates Its operation. 

If the include file option occurs within the body of a procedure or 
within the body of the main ptogram, the Includ file tnuet not contain 
flny USES, LABEL. CQUST, TYPE, or VAP. declarations. Otherwise, the 
compiler accepts include files which contain such declarations even 
though the declarations of the original program have already been 
compiled. 

The Coinpiler cannot keep track of nested include opclona, l,e. an 
Include file must not contain an include file option- This results In a 
fatal Compiler error- 

The include file option makes it easier to cocipile large proeratos 
without having the entire source In one very large file- This Is 

especially useful when the cocibined file would be too large to edit in 
the existing Editor's buffer. 



THE "LISTING" OPTION 

Concrola whether Che Compiler will generate a program llatlngf 
Default velue; L- 

f*SL+*) Instructs the Compiler to save a compiled listing on the 

boot diskette under the filename SYSIHi.LST.TEXT. 

,(*SL-*) Telle Compiler to make no compiled Hating. 

(*?L flletianie*) Tells Compiler to save compiled Hating In the 
specif lEd file. 

Far exan^le, the following will cause the coinpiled lifting Co be sent Co 
the printer: 

(*SL PRINTER;*] 
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The following vlll cause the coinpllfed listing to be sent to a diskfile 
tailed DEM01*TEXT on the diskette nsmed KYDISKj 

(*$L MTDISKjDEMOI.TEXT *) 

The specified filename, which roust be the last item hef ore the *), Is 
used exactly es typed. No suffijc la added» Note that a diskette 
listing file inay be edited just like any other text file, provided the 
fllensroe which la specified contains the suffix -TEXI- 

In the compiled Listingj tha Compiler places uext to each source line 
the line nurahefj segnient numberj procedure number, and the number of 
bytes or words Cbytes for code, iwords for data) required by that 
procedure's declsraticns or code to that point- The Compiler bIeo 
indicates whether the line lies within cbe actual code to be ei^Gcuted or 
is a part of the declarations for that procedure by printing a "D" for 
declaration and an Integer Ci-.9 to designate the level of atatetnent 
nesting within the code part* 

Here la a saiople liatlng, to which column headings have been added; 



Source Segment Procedure 
line number number 



1 
Z 

a 

5 
6 

7 

9 

10 
11 
12 
13 
U 
15 
16 
17 
IB 
19 
20 
21 
22 
23 
24 
25 
2£ 



Lexical Byte nucibef Program 

level wlcbln procedure text 



1:D 


I 


(*$L SCRATCH aiSTUTEXT* 


1:I> 


1 




1:D 


1 


PROGRAM EOCTOR; 


l!D 


3 


VAR DAY, CURE :INTBGEB; 


l!D 


5 




2:D 


I 


PROCEDURE DOSE; 


2:0 





BEGIN 


2:1 





URITECAH apple a DAY' 


2;1 


26 


WRITEf AND ') 


2:0 


A3 


END; 


2:^ 


56 




3sD 


I 


PROCEDURE TREATMI;KT; 


3:0 





BEG IK 


3:1 





FOR CUREi^l TO' 4 DO 


3:2 


11 


BEGIN 


3:3 


11 


DOSE 


3j2 


11 


END 


3J0 


13 


EKD; 


3:0 


34 




1:0 





BEGIN 


1:1 





FOR DAY;-0 TO 25 DO 


1:2 


13 


BEGIN 


1:3 


13 


TREATMENT; 


1:3 


13 


WRITELNC") 


1:2 


35 


END 


1:0 


35 


END. 



The infomatlon given In the compiled listing can he very valuable for 
debugging a large prograsi. A run-tltue error message will indicate the 
segment number, procedure number, and the offset (byte nunher within the 
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current procedure) where the error occurred. 
Here la a saniple run-tinie error stef^eage; 

EXEC ERR ^ 10 

Sfl 1, ?P 7, I# 56 

TYPE <SPACE> TD CONTINUE 

T^ere S*^ Is the Eegmetit numter, p# is the procedure number, and If le 

the byte nomber In that procedure where the error occurred. 



THE "NOLOAD" OPTION 

This Option prevents the code of a UNIT used by the proerain (see Chapter 
55 from being kept in tnem^ry when the proKram Is executed- Instead, the 
IRlT's code is In memory only when some poction of It ia active- 

Default value: M- 

(*$N+*) UNIT code will be loaded only when active. 

f*SN-*} OKIT code will be loaded dfi soon as program 

begins executing* 

The (*SK*> option ehould be placed at the beginning pf the main 
prDgram. Note that use of the (*SN+*) option does not prevent the 
InlclallzatioTi portion of a UMlT froR being executed. 



THE "PAGE" OPTION 

If a listing is being produced, the P option causes one tDrra-feed (ASCII 
12) to be Inaerted into the text of the listing^ just before the line 
containing the P option. For example, if your progracn contains the line 

(*$P*) 

that line will appear at the top o£ a new page when you print the 
program's compiled listing. 



THE "QUIET COMPILE" OPTION 

The Q Compiler option la the "quiet compile" option which can be used to 
suppress the screen messagea that tell the procedure names and line 
mjinberf: and detail the progress of the coftipllationi 



66 APPLE PASCAL LANGUAGE 



^ 


H 


m 


^ 


E 


^ 


K 


]j 


w 


!i 


E 


^ 


fe 


^ 


E 


3 


g 


d 


m 


■1 


M 


m 


E 


a 


E 


^ 


E 


3 


E 


4 


l» 


<4 


1= 


3 


l! 


^ 


tl 


i| 


l£ 


3 


K 


SI 


■ 


a 


m 


^ 


k 


-3 







Default %'alue; 



(*S0-*) 



Causes the Compiler to suppress output to the 

flc reen* 

Causes the Compiler to send procedure name and 
line number mefisages to the acreeti. 



ThlE is moatly useful when the CONSOLE; device is not the Apple's TV 
or utonitor screen, for example if you are usJng a printing terminal. 
norriifll use with yottr Apple, this option is not needed. 



In 



THE "RANGE CHECK" OPTION 

With the (*Srt+*) option, the Compiler will produce code which checks on 
array and string suhscripts and on assignments to variables of subrange 
artd string types. 



Default value: 



R+ 



(*$R+*) Tijrne range checking on, 

(*SB-*) Turns range checking off- 

Kote Chat programs compiled with the (*SR'-*) option selected will tun 
slightly faster. However if an Invalid index occurs or an invalid 
assignment is made, the program will not be tennlnated with a run-time 
error. Since you should never assume that a program ia absolutely 
correct, use C*$E-*) only when speed is critical. 



THE ^'RESIDENT'* OPTION 

This option forces the code of a specified UHIT or SEGKEKT procedure co 

be kept in memory, for as long as the procedure that contains the option 
ia active. It can thus override the automatic swapping out of a SEGMENT 
pROCEDUfiE or fUWCTlOH {see Chapter 5), and the autoraatid swapping out of 
a imiT caused by tlie KOLOAD option (see above). For example ^ suppose 
that hfOBY is a large SEGMENT PROCFDURI'. -NorTnally It is in tireriory only 
T**ien it le active (thus allowing the memory space to be used for 
something else)* But another procedure! FATP^ calls MOBY repeatt^ly* Ve 
don't want the dist; drive to be whUzing JiOBY In and out of memory each 
time RATS calls it^ so we make MOBY a "resident procedure" within RATS: 

PBOCEDLlRE PATS (HATS^ SATS, CATS ; INTEGER ) ; 

VAK FQON, MOON: STRING; 
BEGIN 

<*SR MOBY*) 
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Kdw MOBV will be kept in memory as long aa RATS is active. The resident ^ 
option must Ifflmediately fellow the BEGIN that starts the procedure " 

body. 

The realdeTit option is also useful in connection with the noload option 
deflccibed above « 



THE "SWAPPING" OPTION 

Thie option determlnee whether or not Che Compiler operates In 
"awapplna" mode. There are two main parts of the Compiler; one 
processes declAratlons; the other handleB etatEments- In the S+ 
flwapplna mode, only one of these parte le in main mecoDry at e time. 
Thia makes about 3900 additional words available for ayinbol*table 
fltorage at the coat of slower compilation speed (approximately 3^0 
Unea/mlnute In S- trode, vetgue about 150 lloea/ciinute in S+ node) 
because of the overhead of swapping the Compiler eegnents in from disk* 
Thla option muat occur before the Compiler encounterH any Pascal 
Byi^tax. 

Default valuer S- 

C*?S+*) Puts Compiler in swapping inode. 

Puts CotDplXer in non-swapping raode« 









Compiler does even more swapping than with the S+ 
option. The program compilea bcIII n»re alowly, but 
still ntore room le left in memory for eyrabol-table 
storage- 



The S+ option should be used when compiling a UNIT, 



THE "USER PROGRAM" OPTION 

This option detennlnes whethEr thia conpilatton is a ueer program 
coorpllation^ or a ccraipllaclon of a system prograsit 

l^efault valuer D+ 

C*S1J+*) Informa the Compiler that this cojnpllatian is to take 

place on the user program lex level* 

{*$U_*) Tells the Compiler to compile the program at the eystetP 

lest level. Thia setting of the U compiler option 
also causes the folloulnjg options to be set: R-, G+, T- 

NOTE: The tJ- option will generate prograniB that do not behave as 
expected. Not recommended for non*sys tenia irork unless you know its 
method of operation* 
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THE "USE LIBRARY" OPTION 

This option consists of the letter U and a filename. The nanted file 
becomes the library file in which subsequent USEed UNITs are sought. 
The specif led filename, which mast be the last item before the *) , Is 
used exactly as typed- ^o suffix Is added- 

The default filename for the library Is SYSTEM. LIBRARY, on the boot 
diskette* If any t^SEd DNITs are in the boot diskgtte'e SYSTEM. LIBRARY, 
and you refer to those UNITs firet, you do not need the Use-llbraty 
Conquer option for those UKITs- See Chapter 5 for cnore details on 
UNits^ 



Following Is an example of a valid USES clause 
Cot^iler option; 



ei^loylna the D filename 



USES UHITi,™iT2, <*FOUND IN ASVSTEM.LIBftAHV*) 
C*$U MYDISKjA.CODE *) [JN1T3, 
(*SU APPLE1:B-LIBEIAIY *) 
lJNIT^,Ub3ITS; 

Notej la a U filename optian* you may not use the * or *; notation to 
specify the boot diskette* 



Sooe programfi require the Cooqiller to access another diskette file *^ 
for exacnple, an "include" file. When this ia done# 2K of memory Is 
retiujred for the diskette directory* If the program Is very large, this 
additional memory Is not available and the compilation falls- If thia 
happens to you^ try the following technique: 

Use the Filer co^imand HCake to create a A-block fll* named 

SYSTEM. SWAPDISK on the same diskette thst contains the Compiler. Kow, 

when the Con^iler re&ds a diskette file during compilation, it will 

write out 2K of Information from memory to SYSTEH.SWAPDISK* thus freeing 

2K of memory for the diskette directory* When the diskette directory is 

no longer needed, the 2K of Information ia read back Into memory from 

3YSTEH.SWAPDISK. 



i 
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COMPIUR OPTION SUMMARY 



Ail CotLiplier options are placed in the source text in "dollar-ei 
cotanents": 



en 



{*$DpCiOD'*) 



Examples: (*SG-*) 

(*3I RIRTLE.TEXT *) 



UorapUerr-opciun speci flcationa nay be cgjobJned in one set of C*5".*) 
brackets : 

(*$option, option*) Example: (*$F-,S+,C+*) 

If a filename la specified^ it nuat be the last item before Ehe *) * 






Following characters are placed directly into codeflle. 

AllovB GOTO atateiQenta, 

Forbids GOTO statements fdefault). 



1+ 

I- 



Generaces l/O-^checklng code (default). 
[Jo I/O checkings 
I fileaame Includes named source file In eocnpllatXcn. 

^'*" Sends coTT^iled listing to SV5TEH*LST.TEXT, on booC disk, 

^^ Makes no coinplled listing (default). 

L £il&nanii> Sends coB^iled listing ta named f i le » 






freventa UtJITa Erom being loaded until activated. 
Loads UNITS immediately when program runs {defaulc). 

Inserts a pa^e-fecd Into compiled listing- 
Suppresses screen messages. 
Sends procedure names and line nmnbers to COHSOLE: (default) 

Generates tange-checklnf; cade (default). 

Ho range checking, 

Ke&ps nacned procedure loaded wliile current one is active* 

Puts Compiler in swapping mode* 
Cotapiler does even aoce swapping* 



Q+ 

Q- 

it- 

R name 

S+ 

S+** 

S- i'Jon^'Swapplng mode* 

^^ CoDipllea user program (default). 

^■~ CocqaiXes ayatcm proijrdin- 

U filename Specifies naine of Library file for finding UMITs, 
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INTRODUCTION 



Apple Pascal supports the geparation of procedures and functions, or 
groupfl of thenii from the main program- When you are developing a large 
or complex progrflci» this can be very uaeful as it allows you to reduce 
the size qf code files, Ed reduce the memory space used by the program 
and to use a sec of procedures and functlona in mflre thati one prograini. 

Separation cati te achieved both at the P-code level and at the source- 
language level* At the P-code level, any procedure or function can be 

designated aa. a SEGMENT, The reeult Is that its code is not loaded Into 
memory until It is called by sone other part of the program. As soon as 



the SEGHEKT procedure or function la no Longer active it 1b ^^awapped 
out;" that 1b, Its meuiory space is cnade available for some other use 



fluch as dynamic metnory allocation or swapping in another SEGKENT- 
technique la aometlniea called "overlayingi*' 



This 



At the Source -language level, a group of one or more procedures or 
functions can be compiled aeparetely aa a UNIT* The result of compillne 
a UNIT la a library file; It can either be used directly or incorporated 
into some other library flic such aa SYSTSI- LIBRARY* 

Separate compilation has several advantagea in the developnent of any 

large or coinpllcated program, because it allova you to approach the task 
as a group of smaller taaks ^ich are linked together In a simple and 
logical way* Several of the powerful features of i^jple Pascal are 
Implemented as UNlITs, aa we will see in Chapter 7. To u6e a separately 
compiled UNIT, a program inufit contain a USES declaration with Che name 
of the IJNIT; the program la then called a heat prograin* 

There are two klnda of UNlTgi Regular UNlTs and Intrinsic UNTTa* When a 
host program USIS a Regular UNIT, the UNIT'b code is Inaerced into the 
host program's codeflle by the Linker. This need only be done once 

unless the UKIT is ncdifled and recompiled; then It must be relinked 
into the host prograta* 

Wh.en a host progran USES an IntrlT^slc UNIT, the LfNIT's code retnalne In 
its library file and ±a automatically loaded into luemory when the host 
program Is executed- Thia keepa the size of the hose program's codeflle 
dovn, which ia particularly Important If many programs use the UNIT. It 
fllflo allows the UNIT to be iDodlfled and teconipiled without the need to 
relink* 

^fl Compiler's NOLOAD and RESIDENT options (see Chapter 43 allow further 

control over the handling of Intrinsic UNITg and SEGMENT procedures and 
functions* NOL0.AU prevents any UNIT ftoni being automatically loaded 
until its code is activated by the host program* The RESIDENT option 
can Etodify the effect of NOLOAD or of a SEGMENT procedure or function J 
it forces a procedure or function to be kept in tiKmory over a specified 
range of program execution — specifically, as long aa the procedure or 
function containing the RESIDENT option Is active, the procedure named 
in the RESIDENT option is kept In memory. 
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Finally, there is the EXTERNAL nechaniam. This allowa a procedure or 

function to be declared in a Pascal host prograTn, without any atatements 
eatcept a heading and the word EXTERNAL- The procedure or function ia 
implemented separately In aaaembly language, aasembled, and then linked 
into the host proei"sm with the Linker. ThiH can be advantageous tot 
procedures or functions vtiich Eoust run very fast* 



g 



■ ^ 

m ^ 

m 3 

E !4 

E 3 

B il 

B a 

B I =1 
4 



PROGRAMS IN PIECES 73 



SEGMENT PROCEDURES 
AND FUNCTIONS 



Declarations of SSCHENT procedures and functione are Idetitlcal to 
ordinary Pascal procedures and functiotie except cliat the word PROCEDUFE 
or FUNCTION tg preceded by the word STCKENT, For eKample: 

SECMFINT PROCEDURE INLTULIEE; 
BEGIN 

(* Pascal stacenenta *) 
ENB; 

SEGMENT FUNCTION FFTfDOtWlNjMPTPJ : NFTRj 
BEGIN 

f* Pascal statements *) 
ENDj 

Program behavior dQ[?s net differ; however, the code and data for a 
SEGWEHT prncedure or function are in memory only vdiile the ptacedure or 
funccton le actually running. This can be irandified by use of the 
Ct>inpl]er cptinn (*5R nane*] as explained In Chapter 4» 

Any procedure or function definition may havo the word SECKEMT- This 
Includes FORWARD definitions and nested definitions. 

The advantage of using SEGMENT procedures la the ability co fit large 
prORrains Into the available memory. To write suth a progranij divide It 
Into two or more tr.ain tasks which are Implemented as SEGMENT 
procedures. To be effective, each SECMFNT should be substantial In sLze 
and the program should be designed go that SEGMENTS are not swapped In 
and out too frequently. 



REQUIREMENTS AND LIMITATIONS 

The disk which holds the code file for the program cnust be on line (and 
in the sarae drive ae when the program was started) whenever one of the 
SEGHEKT procedures la to he called. Otherwise, the system will attempt 
to retrieve and execute whatever Infortnatlon now occupies that 
particular location on the disk now in chat drive, usually with very 
displeaslnji results. 

SECNEST procedures must be the first procedure declarations that contain 
code-generating statements. 
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LIBRARIES AND UNITS 
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So far, we have seen Pascal programs which are compiled Into codefiles; 
a codeflle can be R(un or eX(ecuted. Now we will consider UNlTs, which 
are compiled into Itbrariea. Two or more librarioa can be combined Into 
one file. A library is not R(un or eXfecuted; instead, it ts used by 
one ot more programs - 

A library contains code for procedures and/or functiona which are 
available to any program that uses the library^ juat as if they were 
defined in the program Itself* For example:, the Apple Paflcal Systein 
comes with a library called SYSTEM. LIBRARY which contains code for 
several UNITs; one of the UNlTs is called TITRTLEGRAPHICS, and it 
provides a set of procedures and ftinctlone for high-resolution graphics 
on the Apple. To use these procedures and functions, a program need 
only have the line 

USES TURTLEGRAFHICS; 

after the progran heading- The program can then use a TURTLEGRAPHICS 
procedure such as TURNTO or MOVK* 

You can create and compile your own UNITh, and either add then to 
SYSTE34. LIBRARY or build your own libraries by uslns the LIBRARY utility 
described in the Apple Pascal Operating System Reference Manual* 

If a UNIT used by your program Is contained in the SYSTEM -LIBRARY file, 
a R(un coicmwind will automatically invoke Che Linker to d-o the necessary 
linking- Otherwise, jjfou rtwst explicitly invoke the Linker* Note that 
if the UNIT is not contained in the SYSTEM, LIBRARY file* you mi&t use 
the (*5lJ filename*) option of the compiler to tell the compiler which 
library file contains the unit* The (*5U filename*) Is placed anywhere 
before the appearance of the UNIT name In the USES declaration. 



UNITS AND USES 

The source text for a UNIT has a form aomewhat similar to a Pascal 
program, as explained in detail further on* Briefly, it consists of 

four parte: 

- A heading* 

- An INTERFACE part which defines the Way the host program 
comoiunlcatGs with the procedures and functlonB of the UNITi 

- An IMPLEMENTATION part which defines the procedures and 
functions themselves* 

- An "Initialization" which consists of a BEGIN and an END with 
any number of statements between them* Tills Is the "main 
program" of the UNIT, and Is automatically executed at the 
beginning of the host prograEn- Note that the initialization 

PROGRAMS IN PIECES 75 



oAy consist of just the BEGIN and END, with no stateuents 

be ewe en them. 

There are two different flavors of DNITs called Regular and Intrlnalc- 



Regular UNITs 

The heading of a Regular UNIT baa the fgrra 

DKIT name; 

The UNIT is linked Into the host program just once after the proEran Is 
corcplled, atid the entire UNIT'b code la ectually inserted In the host 
program's codeflle at that cine. 



Intrinsic UNITs 

Intrlnalc UNITs can oflly be used by Inscalllng them ±n the 
SYSTSI. LIBRARY file- This is doiiE after compilation by Qsing the 
LIBRARY utility program (see Apple Pascal Operating System Reference 
Hanual ] * 

An Intrinsic UNIT Is "pre-llnked," and its code la never actually 
inserted into che host program's codefile* When you ft(un ihe host 
program^ the Linker la not called and does not have to be on line- The 
Intrinsic UNIT'e code la load«d into memory when bhe hoet program 1b to 
be estecuted- Thus an Intrinsic UNIT can be used in many different 
programs » but there Is only one stored copy of the UNIX's code- 

This can be especially useful when writing for a one-drive system which 
does not hsve room for the Linker or for large programs on the main 
Gystem diskette. Note that the SYSTEM*LIBRARY file must be en line each 
time the calling program Is executed. 

The heading of an Intrinsic DHIT has the forni 

UNIT Dsme; 

INTRINSIC CODE csegmitn fBATA dsegnum] ; 

where caegnum and dsegnum are the segment numbera to be associated with 
the UNIT in when it is installed in the SYSTEM. LIBRARY file. Vou choose 
these nutnhers, and the systept uses theca to Identify the UNIT at run 
time* Segment numbers range frQci ^ to 31| but certain nurabexs between 
and IS must not be used (gee below). The UNIT will generate a data 
aegment If It declares any VBrlahles not contained in procedures or 
functioriLS , 

The code segment will be associated with segment csegnum and Its data 
aegment (If there is one) will be associated with eegtitent dsegnum. 
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Every unit in a library has a specific segmeni: nuniher associated with 
it. The segment numbers used by iteas already in the library are shown 
In parentheaea by the LIBRAJlV and LIBMAP utility programs (sue Apple 
Pascal Operating, System Reference Manuel)* In choosing segnieiit nuinbets 
for an Intrinsic UNIT, the consLjralnc is that when the host prograin 
runs f the segment numbers used by the program must not confllct- 
Dbserve the f ol lowing : 

- While any progran is executing» the system uses segment eJ and 

the main program body uses segment 1. Tliereforc^ never use 
these numbers for an Intrinsic UNIT* 

- Segments 2 through 6 are reserved for use by the system. 

- If the program declj&ree any SEGMENT procedures or functions, 
these procedures or f unct Ions use sequent ial ly increasing 
segEnent nvimbers starting at 7* 

- Each tlKIT used by the program uses the segment number shown in 
Che library listing. 

- If possible, avoid any duplication of segment numbers in the 
library. 

Generally, it la a good idea to use eegment numbers In the range from 16 
through 31. 



J 



The compiler's SWAPPING option, 

should always be used when a UNIT is complied. It should precede the 
heading of the UNIT. 



The INTERFACE Part of a UNIT 

The firet part of e UNIT Is the INTERFACE- 

The INTERFACE part immediately follows the UNIX's heading line. It 
declares constants, types » variahles, procedures and functions that are 
public -^ that Is, the host program can access them just as if they had 
been declared In the host progran. The INTERFACE portion Is the only 
part of the UNIX that is "visible" from the outside; It specifies hew a 
host program can comntunlcate with the UNIT. 

Procedures and functions declared in the INTERFACE are abbreviated to 
nothing but the procedure or function name and the pararaeter 
specifications, as shown In the example below. 
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The IMPLEMENTATION Part of a UNIT 

The IMPLEMENTATION part iTnniediately follows the last declaration in the 

INTERFACE. 

The IMPLEMENTATIOM begins by declarlrig those labels, constants, types, 
variables, prQcedures and functions chat are private '— - that ig» not 
accessible to the boat program. Then the public procedures and 
functions that were declared in the INTERFACE are defined- As shown in 
the example bclav* they arc defined without parameters or Eunction 
result types, since those have already been defined tn the INTERFACE. 



The Initialization Part of a UNIT 

At the end of the IMPLEMENTATION part^ following the last function or 
procodure, there is the "initlaliEacion" part- This Is a sequence af 
atatecents preceded by BEGIN and terminated with END, The reetllting 
Code runs automatically when the hast program is executed , before the 

host projJ,ran is mn. tt can be uaed to make any preparations that fiey 
be needed before the procedures and fLtnctlons of the UNIT can be used* 
Eor exatiple, the Initialisation pare of the TRANSCEMD UNIT in 
SYSTEM-LIBRARY generates a table of trigonometric values to be used by 
the transcendental functions- If you don't want any initialisation to 
take place J you must still have the END followed by a period ' 



AN EXAMPLE UNIT 

Let's sketch out an iniaginary Intrinsic UNIT that needs a DATA segment, 
to denonstrstg the information given abQve* 



E 
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£*$S-f-*) <* Swapping Is required for compiling UNITs *J 

UNIT FROCj INTRINSIC CODE 25 DATA 2&; 

INTERFACE (* This stuff Is public *) 

CONST FLYSIZE = 10; 
TYPE WARTTYPE = (GREEN, BKOWN) ; 

VAR FROGNAME:STRING|2i5]; (* Will need Data segment *> 
PROCEDURE JUHP(D1ST:INTH<;eR); 
FUNCTION WARTS! INTEGER; 



IMPLEMENTATION 

CONST PI = 3*U159; 
TYPE ETC - 3.-13; 
VAR FROCI/IC: INTEGER; 

PROCEDLfRE JUMP; 
BEGIN 

FROGLOC ;- FROGLOC + DIST 

END; 



FUNCTION WARTS; 
BEtlN 

(* Function definition here *) 

END; 

C* More procedures and functions here *) 



BEGIN 

C* Ini Clallzatlon code, i f anvi Roee here *) 
END- 



(* This stuff is private *) 



(* Note; no paratneters here *) 



Variables of type FXLE imist be declared in the INTERFACK part of a 
UNIT. A FILE declared In the IMPLEMENTATION part vi U [;ausG a syntsx 
error upon compilation* 



USING THE EXAMPLE UNIT 

The UPJIT above, properly completed, would then be compiled- Then the 
UNIT would be installed In SYSTEM, LIBRARY^ using the LIBRARY utility. 
Once in the library, che UNIT could then be used hy any Pascal host 
program- A sample prograiri to use our UNIT Is sketched out below: 
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PROGRAM JIMP Eft; 

USES FKOCi 
CONST .*. ; 
TYPE ... I 

VAR . . J 
PROCEDDRE . - 
FUHCTION . .. 

BEGIN 



END. 

A program must ladlcace the UNlTs that it USES before the declflratlon 
part of the program; procedures aad fuuctious icay not contain their own 
USE declarations. At the occurrence of a USES declaratiau, the Compiler 
references the INTERFACE part of the UNIT as though It were part of the 
ho&c text itself. TherGfore all constaats^ types, variables* fuiictlouSf 
and procedures publicly defined lii the UNIT are global* Name coiiflicta 
may arise If the US^r defined an identifier that has already been 
publicly declared by the UNIT. If the UNIT is not in the 
^STEM*LIBRARY, the USES declaration must be preceded by a ''use library" 
option to cell the compiler what library file contaliis the UKIT* 



NESTING UNITS 

A UNIT may aleo USE another UNIT, in which case the USES declaration 
must appear at the beginning of the INTERFACE part- For exafflple^ our 
UNIT FRDG might use the graphics UNIT TURTLEGRAPHICSl 

iraiT FROGj INTklNSIC CODE 25 DATA 26; 

INTERPACE 

OSES TITRTLEGRAPHICS; 
CONST FLYSIZE - 10j 



etc* 

When you later use such a UNIT, your host program must declare that it 
USES the deepest nested UNIT first: 

PROGRAM JUMPER; 

USES TURTLEGRAFtilCS.FROG; 

There la one liniltattOH; an Intrinsic UNIT caauot USE a Regulflr UNIT. 
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CHANGING A UNIT OR ITS HOST PROGRAM 

For test purposes, you rcay define a Regular UKIT right in the host 
program, after the heading of the host program. In thia case, you will 
compile both the UNIT and the host program together. Any subsequent 
changes in the UNIT or host program require that you recompile both* 

Normallyt you will define and compile a Regular UNIT separately and use 
it aa a library file (or atore it in another library by using the 
LIBRARY utility). After coniplling 9 host program that uses such a UNIT, 
you inijaC link that UNIT into the hos t program's co defile by executing 
the litiker. Trying to Rfun an unlinked code file will cause the Linker 
to run automatically, looking for the UNIT in the system library. 
Trying to X(ecute an unlinked file causes the system to remind you to 
link the file. 

Changes in the host program require that you recoraptle the host 
program* Vou nnust also link In the UNIT egain, If It is not IntrinsiCf 

Changes in a Regular UNIT require you to recompile the UNlTf and then to 
reeoniplle and relink all host programs £or other UHITs) which use that 
UNIT, 

INTRINSIC CNITs and their host programs can be changed ea described 
above, but they do not have to be relinked- 
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EXTERNAL PROCEDURES AND FUNCTIONS 



EXTERNAL procedures (.PRDC's) are separately assembled assembly- 
IflnguHge procedures, often stored in a library file- Host proErams that 
require EXTERNAL procedureG must have them linked into the cdir.plled code 

file. 

A host prograiR declares that a procedure (or function) Is EXTIlRMAL 1ti 
much the same Way as a procedure Is declared FORWAHD* A standard 
heading is provided, folloi^red by the keyword EXTEENAL* 

PHOCEEURE FTlAM>riS (WIDGET, CIDlB^flONi INTEGER) j 

EXTERNAL; 

There Is one special rule for the heading of an EXTERNAi procedure or 
function: A VAR paraineter can be declared without any type. 

Calls to the EXTERNAL procedure use standard Pascal syntax, and the 
Compiler checks thar calls to the EXTERNAL aftree In type and number of 
parameters with the EXTEkNAL declaration. U ie the user's 
rceponsibility to ensure that the aasembly- langtiege procedure respects 

the Pascal EXTERtCAL declaration- The Linker checks only thfit the number 
of words of parameters agree between the Pascal and assembly-'language 
declarations. For more Infonnation see the Apple Pascal Operating 
System Reference l*^aoual. 

The corrventlons of the surrounding system concernirg register use and 
calling sequences must be respected by writers of saserab ly-language 
roytlnea. On the Apple, all registers are available, and zero-page 
hexadecimal locations GS through 35 are available as temporary 
variables. However, the Apple Pascal system also uses these locations 
as temporaries, so you should not expect data left there to be there 
when you execute the routine Che next time* You can save variables In 
non-zero page memory by using the .BYTE or «VI0R1> direct ives in your 
program to reserve space. 

For assembly language functions (.FDNC's) the sequence is essentially 
the sane, except that: 

— Two Words of aeroa are pushcid by the Compiler after any 

parameters g re put on the Stack- 

- After the stack has been completely cleaned up at the routine 
eatit time, the .FU^3C must push the function result on the 

B tack> 

For an e^^aniple of an EXTERNAL assenibly-^tan^uaEf procedure and an 
EXTERNAL assembly-langu3£G function^ called from a Paacal program, ece 
the example In the Apple Pascal Operstinj; Fystem Reference Manual. The 
EXTERKAL routine In that exansple is nianually Linked Into the calling 
program- 
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IDENTIFrERS 



rhe underscore character _ Is allowed in IdenclElera; however, the 
compiler ignores it* Therefore the Identifiers 

FIG_LBAr 
FIGLEAF 

are equivalent* (Ihe Apple keyboard does not have the imderaccre 
characteri but some external terminals doO 



CASE STATEMENTS 



Iti Standard Paacali If there Is no caee label equal tc Che value iQf the 
caee selector, the result of the case statentent i^ undefined. In Apple 
Fascfilp If there Is no case label matching Che value cf the case 
selector, Chen the next atateoienc executed is the stetement fallowing 
the case 9Cecetiienc> 



COMMENTS 



The Appli; Faecal ccMnpiler recognizee any text appearing becveen elcher 
Che symbDls (* atid *) or the symbols { and ) as a comnient* Text 
appearing betveen chese eymholfi Is ignored by Che Coinpller unless the 
first character of the comment la a dollarsigni in vhlch case the 
comnent is interpreted as a compiler option (see Chapter 4i3- 

If Che beginning of the comment is delimited by the (* ayiE&ol, the end 
of the congnent imfit be delimited by the niatching *) syinboli rather 
Chan the ) symbol. When the cominenc heglna with the C aymboli the 
connnient cotitinuea until the Tnstching ) eymbol appeora^o This feature 
allovs you Co '^coaincnt out'" a aecclon of a program vhlch itself concaina 
coEonenta. This applies to external terminals anly, since the only 
coinmenc delinjiter available on Che Apple la the paif (* and *). An 
example of how Che two kinds of comment dellEcitera are used on an 
external terminal: 



( 



XCP I- XCP + l; C* ADJUST FOR SPECIAL CASE.. 



') } 



Tha conpller doi^s not keep track of neaced comments^ When a. comment 
symbol ie encountered, the text is scanned for the matching commept 
synibol* The following text will result in a syntax errors 

C* THIS IS A COMMENT (* NESTED COMMEtTT *) END OF FIRST COMKENT *) 

■^error here* 
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GOTO 



Apple Paecal haa a more limited Eotm pf GOTO staceisent than Standard 

Paacal> The destination of the GOTO stetemenC must be In rhe aame 

procedure as the GOTO statement itself (confllderlnfi the main program to 
be a procedure) f 

The compiler conaldere a COTO BCaCennenc to be Illegal unleaa the 
cotnpiler optiou (*SG+*) Is used; eee Chapter A. 



PROGRAM HEADINGS 



Although the Apple Paecal Compiler will permit a list of file parameters 

to be pr>esent follovlng the prograoi Identifier (as in Standard Fascal)i 

these parametera ar^ ignored by the compiler end have no affect on the 
program being compiled- 



SIZE UMITS 



The follovlng la a list of majtimum alze limitations Imposed upon rhe 
user by the current inpleniencstion of Apple Pascal; 

- HaxiiEuin nunber of bytes of object code In a PROCEDDRE or 
FUNCTION 1b 1200. Local vari&bles In a PROCECURE or FUNCTION 
can occupy a inaxlmum of about lfi000 vorde of uieniory. 

- Maxinmm number of characters In a STRING variable is 255* 
" Maximum number of elements In a SET is 32 * 1&"512, 

- Hascimum nuaber of aegmenta a program can gee is 16* This 

includes one segioeut for the main prograju, one for each 
SEGMENT PROCEDURE and SEGMEKT FUNCTION declared 1b the 
pro^ram^ and one for each Regular UNIT that the proEram USES* 

- Maximum number of PKOCEDUREa or FUNCTIONa vlthln a eegTienc 
IB 149. 

"- Naxlnum integer that can be represented is 32767; mlnlmuiii 
iB -3276S, 

- Haximun precielcn for REAL values is 32 bite- 



EXTENDED COMPARISONS 



Applfi Pascal allovs ^ and <> compariaons of arraya of e>;actly the same 
type end of record structures of exactly the same type* This can be 
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done without Subscripting [In the case df flrraya ) of flEld Identifiers 
(In the case of records). For exacfiple, given the declsTaClDns 

VAJl A: ARRAYLtf.'lSS] OF INTEGER; 
B: ARRAY[6J.. 1(?1 QY INTEGER; 

cihen Che fQllawlng statement Is legAlt 
IF A-0 THEN ... 

and the atatiEiBBnt following the THEN ijill be executed If each element of 
A Is equal Cd the: dorreaponding eleEnent Qf B* 



PROCEDURES AND FUNCTIONS 

AS R&RAMETERS 

Apple Pascal dpea not allow a PROCEDURE or FUNCTION to be declared as 
formal parameter In the parameter iJst of another PROCEDURE or 
FUNCTION* 



Wheu the ORD function la given a BOOLEAN value aa an actual parameter, 
the result la not always or 1* It is moHt unlikely that a vcstklng 
program will ever encounter this sltufitloo» since there Is Uctle reaaon 
CO take Che ORD of a BOOLEAW value. 



RECORD TYPES 



There are two restrictions on recortl type declarations which are 
different Eroin Staudajrd Pascal syntax: 

- A null field list Is jllegal; In other vords the cunGtruttlon 

RECORD ENBj 
will cause an error* 

- A null field victiln the parentheses of a variant field iJBt is 
illegal; In other words a semicolon juat before the closing 
parenthesis will CBuse an error* 



THE ORD FUNCTION 



The ORD function will accept a parameter of type POINTER, and return the 
numerical value of the pointer* 



■• 
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APPLE GRAPHICS: 

THE TURTLEGRAPHICS UNIT 



This graphics package is called 'Tuttlegraphlcs" since it is based an 
the "curtlea" devised by S* Papert and hia coworkers at the 
MaasachueeCCs Institute of Technology- To make graphics fnaay for 
children who might have difficulty understanding CarCeaian coordinates* 
Papert et al< invented the idea of a "turtle" who could walk a j^ven 
distance and turn through a specified angle while dragging a pen along. 
Very elaiple nlgorithrae in this aystem (which could be called "relative 
polsr coordinates") can give more Interesting Images than an algorithm 
of the same length in Cartesian coordinacefl. 



Before any graphics can be used, they tnust he enabled 
declaration lEiiEedlatelv after the program heading: 

USES TURTLEGRAPHICS j 



placing this 



If this declaration appedrs^ the graphics jjrocedurcs and functions 
described in this section can be used- This declaration tells the 
Pascal ayateui to get the graphics programs from the library- The 
SYSTEM. LlBRAKY file nuBC be on line when the program is R(\m or 
eX(ecuced. 



THE APPLE SCREEN 

The Apple screen Is a rectangle, with the origin (X"3,Y*!J> at the LOWER 
LEFT comer. The upper right corner has the coordinates {X=27?, lf"L91 ) . 
Since points may only be placed at Integral coordinates, ail arguraenta 
to the graphics functions are IHTECEHs. (You can supply a REAL 
argumeQCf it will be rounded to an INTEGER.) 

There are two different screen Images stored In the Apple's raeTnory. One 
of them holds the text that you see when the computer is flrat turned 
on* The c?ther holds a graphic image- There are three procedures that 
switch between the modes. They are INITTURTLEj TEXTMODE and GfiAFMDOE. 



THE INinURTLE PROCEDURE 

This procedure has no parameters. It clears the eereen* and allows the 
screen to he used for graphics rather than test- It is a good idea Co 
use this routine before starting any graphics. 

INITTURTLE does a Eew other things as well; the turtle (tnore about It 

later) Is placed in rhe center of the screen facing right, the pen color 

is set to NONE (Enore about this later too) and the viewport is set to 
full screen (read on). 
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THE GRAFMODE PROCEDURE 



This procedure has no parameters. It switches the monitor or TV to show 
the EraphicB screen, without the other Initialization that INITTURTLE 
does. It Is usually used to show graphics in a program that Hwitcbes 
between graphics and text display • 



THE TE)a(VIODE PROCEDURE 

This procedure has no pararaeters- It switches from graphics mode 

(obtained by INimiRTl-E or GRAFMODE) to showing text* When you switch 
to text mode, Che Image that you saw In GRAFMODE is not lost, but will 
still be there when you use GRAFMODE to go into graphics mode again 
(unless ycu deliberately changed it.) Upon termination of any program 
that uses graphics, the system automatically goes back into text mode. 



THE VIEWPORT PROCEDURE 

This procedure has the form 

VTEWPORT (LEFT, RI£JHT, BOTTOM, TOP) 

where the four parameters give the boundaries you want the VIEWPORT to 

have. If you don ' t use this procedure, Apple Pascal aaauEca that you 
want to use the whale screen for your graphics- 

There are occasions when It Is handy to use only part of the screen, 
while safeguarding the rest froir accidental use. For example, a small 
square near the middle of the screen might be selected as a viewport by 
the stateiiient: 

VIEWPORT (130, 150, 0fi, 106) 

This example would allow the screen-plotting of all polntE whose 
X-coordlnates are from 130 through 150 and whose Y-cDordtnates arc from 
e& through 106. 



When a line la drawn using any of the graphic cominandB, it Is 
automatically clipped so that only the portion which lies within the 
turrent viewport 1& displayed. Points whose coordinates are not in the 
current viewport, even those points that would not be on the screen at 
all, are legal but are ignored. 
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This allDVB Honie dramaElc effects. It also allows you to plot off- 
screen all day^ and never see a thing or get an ertcr message. Clipping 
cannot be disabled- 



USING COLOR: PENCOLOR 

The PENCOLOR procedure sets the pen color. It has the fonn 

PENCOLOR (COLOR) 
The almpleet colors are 

WHITE 

UHITRl (two dots wide, for use with green and violet) 

MHITE2 (tvo dots wide, for use with orange and blue) 

BIACK 

BLACKl (two dots wide, for use with green aad violet) 

BLACK2 (two dota wide, for use with orange and blue) 

GREEN 

VIOLET 

ORANGE 

BLUE 
If you'd like the drawing Co be in GREEN^ use the statement: 

PENCOLOR (CREEH) 

It may seem stratige that aside from WHITE, BUCK, (^EEN, VIOLET, ORANGE* 
and BLUE, there are two additional flavors of WHITE and BLACK* Theae 
are due to the intricate (not to aay bizarre) way that color televisions 
produce their color. Interacting with the technique that Apple uses to 
gee a lot of color very econofiilcally> Rather than explaining how this 
all works, suffice It to aay here that WHITE and BLACK give the finest 
llnea possible, and the colors give a wider line In order to make the 
colors show. If yau wish to nake a white or black line tbiat corresponds 
exactly In position and width with a green or violet line then you 
should use WHITEl or BLACKl. If you wish to make a white or black line 
that corresponds exactly tn position and width with an orange or blue 
line, then you should use WHITER or SLACK2. 

On a black-and-^hlte toonltor or TV set| Ju^t use UHITE and BLACK. 
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The renvaioing colors are not really colors at all but are equally 
uaeful ^ 

- NOKE: Drawing with this "color" produces no change on the 
screen* It is useful for moving the turtle without drawing a 
line* 

" REVERSE: Drawing with REVERSE changea BLACK to WHITE and WHITE 
to BLACK. It also changes WHITEl co BLACKl, WHITE2 to BLACK2, 
GREEK to VIOLET and ORANCE to BLUE and vice versa. It is 
rather a raaelf^^l "color"* It allows you to draw, say, a line 
across a complex background and have it still show up- 

- SIADAR: This "color" has been left unused for future 
applications. 



MORE COLOR: FILLSCREEN 

Ihe FILLSCREEN procedure has the fom 

FILLSCREEN (COLOR) 

FILLSCREEN fills the entire viewport with the specified color, for 
example 

FILLSCREEN (BLACK) 
clears the viewport. The Btatecient 

FILLSCREEN (REVERSE) 
makes a "negative" of the contents o£ the viewport. 



% 



When you invoke TURTLEGRAFHICS, a new variable typo called SCREENCOLOR 

is automatically created* It Is defined as followai 

SCREENCOLOR = (NONE, WHITE, BLACK, REVERSE, RADAKj BLACKl, GREEN, 
VIOLET, WHITER BLACKZ» ORAMGE, BLUE, WHITE2) ; 

SCREENCOLOR has all the msual characteriatica of a PaBcal type- It is 

useful when yqu declare a variable that will be used to Btore s. color. 
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TURTLE GRAPHIC PROCEDURES; 
TURNTO, TURN, AND MOVE 

At last we're hack to the imaginary turtle. Iiittlallyi the turtle sitB 
at the center of the acreen» facing right. The turtle can only do two 

things: it can turn or it can walk in the direction It Is facing. As it 
valke, IC leaves behind a trail of ink (!) in the current pon color. 

The imNTO procedure has the fom 

TURSTO {DEGREES) 

where DEGREES is an Integer which is treated Tnodulo 36fli thus its 

effective value is in the range -359 through 359, When Invoked* this 

procedure causes the turtle to turn from its present angle to the 

indicated atigle* is exactly to the right, and counterclockwise 

rotation represents increaalng angles. This comniand never causes any 
change to the image on the screen* 

The TURK procedure has the form 

TimK (DEGREES J 

vher^ DEGREES 1b again an integer iwhlch le treated nudula 360s thue its 
effective value Is in the range -355 through 359. Thla procedure causes 
the turtle to rotate counterclockwise from Its current direction through 
the specified angle. It causes no change to the litiage on the screen. 

The MOVE procedure has the form 

MOVE (DISTANCE) 

where DISTANCE is an Integer- This procedure makes the turtle move IN 
THE DIRECTION DJ WHICH IT IS TOIKTING a distance given by the integer 
DISTANCE* It leaves a trail in the current pen color. The sequence of 
stateinents: 

PENCOLOR (WHITE); 
MOVE C50); 
TURf! (12fl); 
MOVE (59) i 
TURK (120) i 
MOVE (50) 

draws an equilateral triangle, for Injstance. 
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TURTLE GRAPHIC FUNCTIONS: 

TURTLEX, TURTLEY, TURTLEANG, AND SCREENBIT 

These functions allow you to Interrogate the cornputer about the current 
state of the turtle and the screen. 

The TURTLEX and TURTLEY functions (no parameters) return integers giving 
the current X and Y coordinates of the turtle- 

The njRTLEANG function (no paraineters) returns an integer giving the 
current turtle angle as a positive number of degrees- Note that if you 

use TURNTO and then TURTLEANG, the value returned by TURTLEANG may not 
be the same value you gave with TURNTQ. For example, after 

TmHTO(~99) 
TURTLEANC will return 27fl, not -93* 
The SCREENBIT function has the form 

SCREENBIT (X,Y) 

where X and V are screen coordinates » This function returns the BOOLEAN 

VfllLie TRUE if the specified location on the screen is not black, and 

FALSE if it is black. It doesn't tell yoo what color is at that point, 
but only Aether there Is something non«black there or not. 



CARTESIAN GRAPHICS: THE MOVETO PROCEDURE 

Earlier we said that in turtle graphics, the turtle can only walk In the 

direction it is facing. But in Cartesian graphics, the turtle can move 

to a specified point on the screen vlthout turning. The MOVETO 
procedure has the form 

MOVETO (Xj Y) 

where X and V are acTcen coordinates. MOVETO moves the turtle to the 
point (X^¥). This creates a line in the current pen color from the 
turtle's last position to the point CX»V)- 

The direction of the turtle la not changed by MOVETO. 



SPECIAL UNfTS 95 



GRAPHIC ARRAYS; THE DRAWBLOCK PROCEDURE 

The DRAWBLOCK procedure has the form 

DRAWBLOCK CSOURCE, ROWSIZE, XSKIF, ISKIP, WIDTH, HEIGHT, 

XSCREEN, YECREEN, MODE) 

where Lhe SOIURCE parameter Is the name {without subscripts) of a 
variable which should be a two-dlinenslonal PACKED ARRAY OF BOOLEAH {aee 
note below) • All the other pauacietera arE Integers • 

DRAWBLOCK treats eath BOOLEAN element of SOUECE aa a "dot" — true for 
white or false for black- It topiea the array of "dots" for a portion 

of it) frotn memory onto the screen to form a screen lmage> The firet 
dimension of the array la the numibEr of rows in the array; the aecond 
dimension is the number of elements in each row» 

You loay choose to copy the entire SOURCE array, or you may chooae to 
Copy any specified *'wlndow" from the array , using only those dots in the 
array from KSKIP to XSKIP+WIDni and from YSKIP to YSKIP-KIEIGHT* 

Furthermore J you can specify the starting screen position for the copy j 
at (XSCREEN, YSCREENK 

- SOURCE is the name of the two-dimensional PACKED ASRAT OF 
BOOLEAM to be copied (see note below)* 

- SIZE is the number of bytes (not dots) per row In the array- 
You can calculate this from the formula 

2*( <X+15) DtV 16 > 

where X Is the number of dots In each row- 

- XSKIP tells how many horizontal dots in the array to skip avex 
before the copying process is started' 

- YSKIP tellB how many vertical dots in the array to skip over 
before beginning the copying process. Note that copies are 
RWde starting from the bottom up — i te • the f irat row copied 
from the array is the botCdtn row of the screen copy. 

- fflDTH tells how many dots" width of the array » starting at 
XSKIF, will be used, 

- HEIGHT tells how many dots' height of the array, starting at 

YSKIF, Will be used. 

- XSCREEN and YSCREEN are the coordinates of the lower left 

corner of the area to be copied into. The WIDTH and flElGHT 
determine the sl^e of the rectangle. 
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- MODE ranges from ff through 15* The MODE determines What 
appears on the portion of the screen specified by the other 
paraiaetera- It is quite a powerful optlc^n, which can simply 
aend white or black to the screen, irrespective of what is in 
the array, copy the array literally, or combine the contents 
of the array and the screen and send the result to the 
screen. The followine table specifies what operation is 
performed on the data in the array and on the screen, and thus 
what appears on Che screen- (The logical notation uses A for 
the array, and S for the screen. The symbol ~ means NOT*) 

MODE Effect 

Fills area on screen with black* 

1 NOR of array with screen- <A NOR S) 

2 AND of array with complement of screeni (A AND ""S) 

3 Complements area on screen- ("S) 

A AND of complement of array with screen. CA AWT) S) 

5 Complements the array- {"A) 

6 XOB of array with screen- (A XOR S) 

7 WAND of array with screen. (A NAKD S) 

8 AKD of array with screen. <A AND S) 

9 EQUIVALENCE of array with screen- (A = S) 
Lff Copies array to screen* (A) 

11 OR of array with coinplement of screen- (A OR ""E ) 

12 Screen replaces screen- <S ) 

13 OR o£ complement of array with screen* ("A OR S) 

14 OR of array with screen- tA OR S) 

15 Fills area on screen with whice- 

The demonstration prograra GRAFDEMO*TEXT, on APPLE3;, contains many 
examples of how to use the turtlegraphlca routines. In particular, 
procedures flUTTERl, etc, give strings to procedure STUFF, which 
converts them to a PACKED ARRAY 0¥ BOOLEAN named BUTTER; and procedure 
FLUTTER uses the llRAWELOCK routine to display the array HtJTTER on the 
screen* 
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Actually » the SOURCE parameter can be of any type except a FILE type; 
DRAWBLOCK really deals with an array of bits in memory which begins at 
the address of SOURCE and whose sise and organisation depend on the 
other paraaieters. For example, the following procedure uses a single 
BOOLEAM variable Instead of an array- The procedure plots a single dot 
on the screen at specified coordinates (X,Y): 

PROCEDURE PLOTDOTCX, Ys INTEGER 5 ; 
VAR DOT; BOOLEAN i 
BEGIN 

DRAWBLOCKPOT, I,3,5I»1.UX,Y,33 

ENDS 
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However, for most prograjns the most cionvenlent way to handle the array 
iB to use a t«o-dlQiens±onal PACKED ARKAY OF BOOLEAN as described 
prevlouBly* 



TEXT AS GRAPHICS: 

WCHAR, WSTRING, AND CHARTYPE 

Three procedurea allow you to put characters on the graphics 9cifeBn» If 
the turtle le at (X,Y) you can use these procedureB to put a character 
or gtrlng on the ecreen with Its lower left corner at (K,Y). Each 
character occupies a rectangular area 7 dots wide and 8 dota high on the 
Hcreen* 

These procedures use an array stored In the file SYSTEM -CHARSET on 
disketto APPLEl:, This array contains all the charatters used, and Is 
read in by the initialization routine when your program USES 
TURTLEGRAPHICSt If you make up an array containing your own character 
set, you should rename the old SYSTEl* CHARSET and then name your new 
array STSTEJI* CHARS ET (see note at the end of this chapter). 



WSTRING and WCHAR use the procedure DRAWBLOCK to copy each character 
from the array onto the screen* The MODE pars Dieter that they use la set 

by the CHARTYPE proceduFc* 

The WCHAK procedure has the fonn 

WCHAR (CH) 

where CH la a an eicpresslon of type CHAR» This procedure places the 
character on the screen with Its lower left corner at the current 
location of the turtle, i^en this procedure is used, the turtle Is 
shifted to the right 7 dota from its old position* For exaraplej this 
puts an X In the center of the screen: 

PENCOLOR (NONE); 
MOVETO (137,90); 
tfCHA* CX'J 

In this example, note that It was not necesEary to specify a new pen 
color before calling WCHAA. The character is not plotted with the 
Current pen color; rather It depends, on the current MODEj Just as 
DRAUELOCK does- For details, see CHARTYFJi: below. 



The CHAR value passed to WCHAft Is restricted to the first 128 characters 
of the ASCII set as shown in Table 7 of Appendix B. 
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The WSTRING procedure has the form 

WSTRIKG (S) 

where 3 Is an expression of type STR1>3G. An entire string of characters 
Is placed on Che screen with the lower left oorner of the first 
character at the current turtle position. The turtle is shifted 7 dots 
to the right for each character In the string. This procedure calls 
WCHAR for each character in the string. 



<S^ 



The characEers in the STftlNG value passed to WSTRINC are restricted Co 
the first 129 chsractere of the ASCII set aa shown in Table 7 of 
Appendix B> 

The CHAETYPE procedure has the foriE 

CHARTYPE <MODE) 

where ^tODE le an integer selecting one of the 1& MODEa described above 
for DRAWBLOCK. MODE defines the way characters g^t written on the 
screen; It works for WCtlAR and WSTRING just as IC works for DRAWELDCK, 

The default MODE Is Ltf* which places each character on the screen In 
white, surrounded by a black rectangle* MODE 5 is the inverse of MODE 
Ifl: each character is in black Burrounded by a white rectangle- 
One of the most useful other MODEs Is 6, which does an exclusive OR of 
the character with the current contents of the screen* If you use MODE 
6 to draw a character or string and then redraw it at the same location 
with fSODE 6, the effect ifi to erase the character or string, leaving the 
original iraage unaffected. This Is especially useful for uaer coessages 
in a graphics-oriented prograin. 



4^ 



V 

If you wish to create your own charac&er set file for use with WCHAR and 
WSTRIHG, it oust be structured as follows: 

- the file consists o£ l(J2i bytes- 

- Starting with the first byte in the flle> each character in 
the character set Is represented hy 8 contiguous bytes. 

- Each byte represents one row of 8 dots in the character 

image- The first byte of each character repreeentatlon la the 
bottom row of the iniage* 



SPECIAL UNtTS 99 



- The lease Blgtilftcflnt bit of each byte la the Leftmost dot iu 
Che row. 



- The ttioat significant bit of each 
only seven dots each- 



/te iB ignored; the rows are 



Such a file can be created elthet in aBsatnlily languflg^ or in PasQal. in 
Pascal* you can build the character representacions in memory aa packed 
arrays of Che type 0. .255 since each element of such an array is in 

effect a byCct For example, you might use Che declarations 

TT?E CHARIMAGE-PACKED ARRAY [9**7] OF 0.*255; 

CHARSET-PACKED AE^RAY [0* ,. 127] OF CHARlMAGE ; 

CHARFILE-FILE OF CHARSET; 

VAE CHARACTERS iCUAEEET; 
OUTFILEiCHARFILEi 
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OTHER SPECIAL APPLE FEATURES: 
THE APPLESTUFF UNIT 



This section tells you how to generate random nurabersj how to use the 
game paddle and button inputs, how to read the cassette audio Inputs how 
to switch the game-control's TTL outputs and how to generate sounds on 
the Apple's speaker. To use these special Apple features from Pascal, 
you first have to place the declaration 

USES APPLESTUFF; 

immediately after the program heading* If you wish to use both turtle 
graphics and the Apple features you would say 

USES THKTLEURAPHICS, APPLESTUFF; 

since there can only be one USES in e prograia- 



THE RANDOM FUNCTION 

aW^OK Is an lncep;er function with no parameters. It returns a value 
from 9 through 32767. If RANDOM Is called repeatedly, the result is e 
psuedo*-randoTD sequence of Integers . The ataCennent 

WBITELM (RAKDOH) 

will display an integer between the Indicated limits^ 
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A typical application of this function is to get a pseudo'-'randon nuiober, 
aay, betveen LOW and HIGH inclusive. The espreasion 

LOW + RAiroOM MOD (HlCH-LOW+l) 

ia BOEnetimes used where results are not critical, but the values formed 
by this expression are not evenly distributed over Che range LOH 



ftl:^ 
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Chrpugh HIGH. If you want pseudo-rflndom InCQgera evenly dlatrlbuted 
over a rani^s, you can u9e the following function: 

FUNCTION RAND (LOW, HIGH: INTEGER; VAR ERROR : BOOLEAN 3 : INTEGER; 
VAR tlX. C, ID: IKTEGEEj 

SECIN 

KAND i^ Q', 

ERROR := TRUEj 

IF LOW > HIGH TREli EXITCKAND); <*error exit*] 

IF LOW <= THEN 

IF HIGH > HAXIJTI + LOW THEN EXIT(RAND)| (*errQr exit*) 

ERROR ;- FALSE; (*no errors*) 
IF LOW - HIGH THEN RAND :^ LOW 
ELSE BEGIN 

C :- HIGH - LOW + Ij 

MX :- (MAXTNT - HIGH + LOW) DIV C + 1; 
MX :- MX * (HIGH - LOW) + {MX * 1); 
REPEAT D := RANDOM UKTIL D <- MX; 
RAHD := LOW + D MOD C 
END 
ENi); 

If RIGH is not greater than LOW, or the difference between HIGH and LOW 
would exceed MAXIM, RANT! cetums and sets the ERROR parameter to 
tcue* Otherwise, SAND returnB evenly distributed pseudo-random Integer 
values between LOW and HIGH (inclusive)* 



THE RANDOMIZE PROCEDURE 

RANDOMIZE is a procedure with no parameters* Each time you run a given 
profiracn using RANDOM, you will get the same, randora sequence unleaa you 
use kAtJDOMIZE. 

RANLH3Mi;iE uses a ti oie-de pendent location to generate a atartlng point 
for the randDin number generator^ The starting point changes each time 
you do any input or ouCpuC operotion in your program* If you use uq 
I/O, the starting point lor the random sequence does not change' 



THE KEYPRESS FUNCTION 

This function, which has no parametera, retuma true if e key has been 
pressed on the keyboard since the program started or since the last time 
the keyboard was read (whichever is raost recent), KEYPRESS does not 
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read the character from COWSOLE or KEYBOARD or have &ny other eEfect on 
1/0. The atatement 

IF KEYPRESS TflEK READ (KEYBOARD, CH) 

(where CH ie & CHAR variable) has the effect of reading the laat 
character typed on the keyboard, Thia could be used to retrieve a 
character typed while the program was doing aoraething else — for 
Instance, displaying graphics. 

Once KEYPRESS hecotnes true it remaina true until a GET, READ, or READLN 
flccesaea either the INPUT file or the KEYBOARD file, or until a UNITREAD 

accesses the keyboard device. 
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KEYPRESS does not work with an external terminal connected via s serial 
interface card. It will always return FALSE with auch a terminal* 



PADDLE. BUnON, AND TTLOUT 

The PAEDLE function has the form 

PADDLE (SELECT) 

where SELECT la an Integer treated Dwdulo 4 to select one of the feur 
paddle inputs numbered 0, I, 2, and 3. PADDLE retnrnG an Integer In the 
range to 255 whlcb represents the poBitlon of the seleet&d paddle. A 
1S0K variable r&siBtance can be connected In place of any of the Eour 
paddle 9 < 

If you try to read two paddlea too quickly in succession, e.g. 

WRITELN (PADOLE (P)>; 
WRITELN (PADDLE (1)) 

the hardware will not be able to keep up. A suitable delay is given by 
tbe loop 

FOR I ;- TO 3 DOj 

The BDTTON function has the form 

BUTTON (SELECT) 

where SELECT is an integer treated modtiLo A to select one of the three 
button Inputs numbered 0, 1, and 2» or the audio cassette Input numbered 
3. The BUTTON function returns a BOOLEAN value of TRUE If the selected 
aatne-control button Is pressed, and FALSE otherwise. 



SPECIAL UNITS 103 



E 



When Bt3TTONf3) is used to read the audig cassette input, it aanples the 
cassette Input which changes froni TRUE to FALSE and vice versa at each 
zero crossing of the input signal, 

rhere are four TTL level outputs available on the game connector along 
with the button and paddle inputs. The TTLOl]! procedure is used to turn 
these Ducputs on or off. TTLDUr has the forra 

TTLCCT (SELECT, DATA) 

where SELECT is an Integer treated modulo A ro select one of the four 
TTL outputs numbered iS, I, 2, and 3* DATA Is a BOOLEAN expression. 

If DATA is TRUE, then the eelectsd output Is turned on- It retnainB on 

until TTLOLlT is invoked with the HATA set to FALSE. 



MAKING MUSIC: THE NOTE PROCEDURE 

The NOTE procedure hag the form 
NOTE (PITCH* DURATION) 

»*ere PITCH is an integer frora through 50 and DURATION is an integer 
from through 255, 

A PITCH of is ufled for a reat, and 2 through AS yield a tempered 
(approximately) chromatic scale, DURATION Is in arbitrary unite of 
time* 

NOTE (hi) gives a click. 

A chromatic scale la played by the folIoHing ptDgrani: 
PROGRAM SCALE E 

USES APPLSSTDFF; 

VAR PITCH, DURATION: INTEGER; 

BEGIN 

DURATION 1= 100; 
FOR PITCH !" 12 TO 2^ DO 
NOTE (PITCH, DDRATION) 

EKD. 



E 
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TRANSCENDENTAL FUNCTIONS: 
THE TRANSCEND UNIT 



In Apple Taetal* the trattBcendental functions are not built Into the 
language* To use this set of functions you mifit place the declaration 

USES TRANSCEND; 

ImBKdlaCely after the FROGRAH heading* If you wish to use, say, 
APPLESTUFF with the transcendental functions, you would write 

USES TRANSCEND, APPLESTUFF; 

All ANGLE and NUMBER arBumenta are real, and the ANGLE argumencs are in 
redians* All of these functions return real values, and values returned 
by the ATAN function are in radlana* The foUowtng functions are 
provldedj 

SIN (ANGLE) 

COS (ANGLE) 

ESP CUMBER) 

ATAM (!^UMBER) 



(Note; this Is the same function 
as Standard Pascal's ARCTAN) 



LK (NUMBER) 

LOG (NUMBER) 
SQRT fWUMBE'R) 
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INTRODUCTION 



This appendix prcBents a graphics program which Is fully annotated* both 
by a narrative explanation and by qopioua cotinienta In the source text* 
This prQEraBi 1h followed by commGntarles on the demonstration uTaa-r^ma 
supplied with ^ple Pascal. i- n ^^ 

A word of caution Is in order regarding all of these prograioa. They are 
presented so aa to give you exaniples that you can run without any 
cnodlflcatiDQ, and also study the source text to see how It works. They 
are not Intended to be models of the best possible prograTniiJlng 
technl^iue; that would be entirely beyond the scope of this manusl. They 
do work, and they do demonstrate ways of doing certain useful thlnga in 
Apple Pascal. With thig cetitlpti In mlnd» use the programs as learning 
tools. One of the best ways to learn might be to cry Introducing 
modi fl cat lane Into one of them. 



A FULLY ANNOTATED GRAPHICS PROGRAM 



The foilowlnfi demonetration program, PATTERtJS, Is Intended to lllustrato 
Bone helpful points about Apple Pascal. The progrsra creates pleasant 
graphics by draulng a triangle on the screen and then repeatedly 
rotating it fay & few degrees and redrawing It. The points of the 
triangle are always on the edge of an Invisible circle of radlua 95 
(which fills the height of the screen) but apart from that it is a 
random triangle. The angle by which It Is rotated each time It Is drawn 
la also randotij though it is alwaya between 3 and 15 degrees- 

The color uaed to draw the triangle is REVEFSE, which has intriguing 
effects when one icnage is drawn over another and the lines Intersect at 
amall angles* Also* as the triangle la repeatedly rotated and redrawn a 
circular pattern is built upj but eventually the triangle gets rotated 
bank to Its original position. When thla happens, each new Image U 
exactly superimposed on an old one. Because of the REVERSE color* this 
erases the old image! Srfhen all the old Images have been erased, the 
program clears the screen, generates a new triangle with a different 
shape, and atarta all over. 

This repetition continues until the user signals it to halt by pressltiR 
any key. The KEYPRESS function, in the APPLESTUFF unit, can be used to 
find out whether the user has pressed a key, {KEYPRESS Is described in 
Chapter 7.) 

The program is given in full, with comments, at the end of this 
appendix. What follows Is a description of how a program like this can 
be developed- Of course, in real life there are mistakes and false 
starts* Here, for the sake of learning some principles, we pretend that 
the development of the prograra proceeds without a hitch. 
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This Is a fairly connpllcated program^ so we will develop it in 
sections. First we can write a sketchy outline of the progran): 

BEGIN 
REPEAT 

(*Cfeate a random triangular pattern*) i 
TEETA:-(*tandot[i number from 3 to 15*) 
REPEAT 

(*Rotate the triangle, using the angle THETA*)j 
(*DTaw the rotated triangle on the screen*) 
UNTIL (*Coniplete pattern has been erased*) 
UNTIL KEYPRESS 
ENH- 

To fill in thia outline, we begin with a program heading, a USES 
declaration, aome useful constants^ two variable declarationa* and a 
skeleton of the Inner REPEAT statement: 

PROGRAM PATTERNS; 

USES TURTLEGRAPHICSpAPPLESTUFT; 

COWST KUa«2S0; ^iAXY=191i <*Ha»:linuTii X and Y coordinates*) 
RAI1IU5-95V C*Kadlus of pattern*) 

VAR CYCLES: 0.-2; 
THETA: 3.-15; 

BEGIK 
REPEAT 

(*CreaCe a randoiQ triangular pattern*); 

THETA;-C*r3ndora number from 3 to 15*); 

CYCLES. ;-0 

REPEAT 

t*Ratate the triangle, using the angle THETA*); 
PENCOLOR (RE VERSE); 

(*Draw the rotated triangle on the screen*); 
IF (*the rotated triangle matches the original triangle*) 
THEN CYCLES !-CYCLES+l 
UNTIL CYCLES-2 
UNTIL KEYPRESS 
ENS. 

The variable CYCLES is a counter for the nuinber of tiroes the triangle 
has been rotated hack to its original position. Wlien CYCLES^l, the 
circular pattern begins to be erased bec^Lise each new triangle is drawn 
in the REVERSE color an top of a previous triangle. When CYCLES=2, the 
entire pattern has been eraaed- 

We can now begin replacing comnents with actual statements. For 
example, we already liave a variable, THETA, which is the number of 
degrees to rotate the pattern. So it ia natural to replace the first 
cotument In the Inner REPEAT with a call to a procedure named ROTATE 
vhlch takes an INTEGER parameter' Tfje value used for the parameter 
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will be the variable THEIA* ROTATE will need to be declared; now we 
have 



PROCEDURE ROTATE (ANGLE: INTEGER); 
(*To be completed- ♦ ♦*> 

BEGIN 
REPEAT 

(*Create a random triangular pattern*); 
THETA;=(*randDiq number frop 3 to 15*); 
CYCLES : -SI 
REPEAT 

aOTATE(THETA); 



To draw the ttlangle on the screen^ we must first consider haw the 
triangle Is rfipcesented in titeraory* We can think of the triangle as 
three points; how shall we represent a point? A point can be represented 
by two numbers — an X and a ¥ coordinate. Therefore we can define a 
type POINT, as shown below. Then we can represent the triangle as an 
array named TRGL» of cypc POINT* We will also declare a variable C to 
use ds an index for Che array TRCL' 



TYPE POINT-HECORD X:.^^-MAXX; 
Y:0,.MAXT 
END; 

VAR CYCL£S;(J..2; 

THETA!3,,i5^ 
TRGL:ARRAYri,.3] OF POIHTj 



Assuming that the ROTATE procedure leaves the rotated coordinates in the 
array TRGI. and that it leaves the turtle at the third corner o£ the 
triangle, we can uae Cartesian graphics to draw the new triangle: 



PENCOLOR (REVERSE); 

FOR C:-l TO 3 DO MOVETO (TKGL [C] -X, TRGLICl-Y); 



The reicaiiLlng coraoiient in the Inner REPEAT statement calls for testing 
whether the rotated triangle lostches the original one* To achieve thl£ 
assuQS that when the triangle ie first created the coordinates 
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oiE the third corner are saved In a variable named CORNER* Now we need 
only test aa follows' 



IF TEGLtSl -CORNER THEN CYCLES :=C¥CLES+1 



At this point, the program is as follows: 

PROCKAH PATTKRWS; 

USES TUMTLEGRAPHICS.APPLESTUFF; 

CONST MAXX=280; HAXY-191; C*Maxlinui:i X and V coordinates*) 
RA1JIUS^95; t*R.adlua of pattern*) 

TYPE POINT=REC0RP X:0*«MAXX; 
V : 0, , MAXY 
END; 

VAR CYCLES:0.,2; 
THETA:3..15i 

TRGL:ARRAY[i**3l OF POINT; 
C:I,,3; 
CORNEB: POINT; 

PROCEDURE ROTATE (AKGLE: INTEGER); 

(*To be coiGpleted; must leave new corner coordinates 
in TRGL aad leave turtle at third earner.*) 

BEGIN 
REPEAT 

<*Creflte a random triangular pattern*); 
THETA;=<*randora number from 3 to 15*); 
CYCLES :-^ 
REPEAT 

ROTATE (TtLETA); 
PEN COLOR (RE VTIRSE) ; 

FOR C:-l TO 3 DO MOVETO (TRGL [Cl *X, TRGLlCj.Y); 
IF TRGL [3] -CORNER THEN CYCLES :-CYCLES+l 
UNTIL CYCLES^'Z 
UNTIL KEYPRESS 

The Inner REPEAT statement will repeatedly rotate the triangle and draw 

itf using the REVEKSE color, building up a circular pattern on the 

e^cre«:n and then erasing It by drawing over It. Wlien the pattern has 
been erased, the inner REPEAT tertolnates. 
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Now we can begin filling in the outer REPEAT. The atatementa added to 
the outer REPEAT require another procedure. MAJCEXaGL, and a function 
ARBITRARY. 



m\ j4 



The main program Is nearly complete- It remains only to add one new 
3 variable named CENTEJi Cof type POINT), and a few initializing stateraentE 
before the outer REPEAT: 



FUNCTION ARBITRARY CLOW, ETIGH! IHTEGEK) :IBTEGER; 

<*To be cstnpleted; must return an integer value In the 
range LOW*, HIGH.*) 

PEDCEDURE MAKETRGL; 

(*To be coEnpleted' must Leave corner coordinates in TRGL 
and alao Initialize CORNER with coordinates of third 
corner-*) 

BEGIN 
REPEAT 

MAKETRGL; (*Make triangular patcem*) 

rHETA:-ARflITaAliYf3, 15); <*Choose angle for totatlng triangle*) 
CYCL£S:^0j (*Clear the cycle counter*) 

REPEAT 

ROTATE (THETA); 
PENCOLOR (REVERSE); 

FOR C:^l TO 3 DO MOVETO (TRGL [CJ ,X, THGL[C].Y); 
IF THGL[3]=C0RNER THEM CYCLES :^CTCLES+1 
iraTlL CYCLES =2 
UNTIL KEYPRESS 
EMB. 

The outer REPEAT first calls MAKETRGL- Thla procedure^ still co be 
deflnedi chooses EihrGe random points on a circle of radius 95 and stores 
their coordinates in the array TRGL* It also stores Che coordinates of 
the third corner In the variable CORNER- 

Next, the function ARBITRARY is used to asaign a random value Co THETAj 
the number of degrees to rotate the triangle. 
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VAR CTCLESI0. .2; 
THETA:3..15; 

TRGLiARRAY[1..3J OF POIMTj 
C::..3; 
CORNEKjPOINT; 
CENTER: POINT; 



BEGIN 

RANDOMIZE; 

INITTURTLE; 

CENTER, X :=TTJ RTLEX ; 
CENTER.. Y : =niRTLEy ; 

REPEAT 



REPEAT 



UNTIL CYCLEE=2 
UNTIL KEYPRESS 
END. 



(*To get a different sequence each titnre 

fhrograin is executed*) 
(*AIways do this to use TURTLEGRAPHICS*) 
(*The turtle is st the center bEcause 

INIT1WRTLE leaves it there- Save 
Its coordinates In CENTER-*) 



The main progrflm 1b complete, and Tiov we must define the two proeediires 

MAKETRGL and ROTATE and the function ARBITRARY- 

The ARBITRARY function is shown In the complete program at the end of 
this appendix- It la a simplified version of the RAND function given in 
Chapter 7, in the discussion of the built-in function RANDOM. 

RAND handles unacceptable parameters by settlTig a VAR parameter of type 
BOOLEAN, ARBITRARY does not need this error-handling capability since 

it will always be called with constants as parameter* Slmllarlj', RAND 
has a special provision for the ca&e where the HIGH and LOW parameters 
are equal; ARBITRARY does not have this provision, and HIGH must be 
strictly greater than LOW* 

In other cespect&t ARBITRARY is the eaioe as RAKD- Incidentally, the 
complexity of the calculation in both veraions Is due to the fact that 
two nuinh^rs cannot be added or subtracted if the result would exceed the 
value MAXINT (32767)- The function has to get around this limitation by 
using the intemiediate value MX- 
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The MAKETRGL procedure miat choose three randan points on a circle of 
radius 95, with its center ac CENTER. To select three random points, 
the following method is used: 

VAR Iil.,3; 



FOfi. 1:-1 TO 3 DO BEGIN 

C*Move the turtle to Che CENTER point:*) 
MOVETa(CE«TEH.K. CENTER^Y); 

(*Select 3 random direction to move the turtle avay from CEJJTER, 
and store this angle in an array named DIRECTION; this array vlll 
need tO' be declared;*) 
DlilECnON [I] :=ARBITRAR¥(0,359) j 

(*Turn the turtle lo the selected direction:*) 

TllRKTO(DIR£C'rtON[I] ) i 

(*Move out to the edge of the circles*) 

MOVE (RADIUS); 

(*ytore the turtle's coordinates In the TRGL array;*) 
TltGLdJ .K;=TURTLEX; 
TRG1[I] ,^:-TURTLEY 

END 

The DIRECTION array will be used by the ROTATE procedure, so it vlll 
need to be declared at tine beginning of the program — not within the 
MAKETRGL ptocedure. 

Since we don't want Co draw anything at this point, we aet the color to 
MONE before stactlng the FOU statement. After three tlines through the 
FOR Statement, the turtle Is at the third corner of the triangle^ so we 
save Its position in the CORKER variable for use In the main program* 
The complete procedure Is 

PROCEDURE WAKETRGL; 
VAR 1:1, .3; 
BEGIN 

PEN COLOR (NONE); 

FOR 1:=1 TO 3 DO BEGIN 

HOVETO(CENTEll, , CENTER *Y>; 
DIRECTION [I] : -ARBITRARY (0, 359); 
TUHJJTO{DIRECTIONU] ; 
HOVE (RADIUS) I 
TaOL[I].X:=TLrRTLEX; 
TRCLlU^Yi'^TUEtTLEY 
END; 

COEtNER.X.:-TURTLEX; 
Ca&NER^YioTURTLEY 
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The ROTATE procedure works very ffiuch like the MAKETRGL procedure, but 
Instead of using random angles it uses the anglea found in the DIRECTION 
array ^- after adding ANGLE to each of them and taking the result MOD 
360- It stores the resulting points In the TRGL array, but does not 
change CORNER. The effect Is to replace each point In TRGL with a nev 
point created by rotation througb jWGLE degrees. The cooiplete ROTATE 
procedure l3 

PROCEDURE ROTATECANGLEjINTEGER); 
VAE l!l.*3; 

bSgin 

PENCOLORfNONEJ; 

FOR I;*^l TO 3 BO BEGIN 

MOVETO(CENTER.X, CENTER. Y); 

DIRECTI0N[I];'CDIHECTI0N[I]+ANGL£) «0D 360; 

TDRNTO <DIREGT10N[I] )j 

MO VE< RADIUS); 

TRGLJIJ *Xj=TURTLEX; 

TRGLEI] .T:-TURTLEY 
END 
END; 

Note Chat the MOD 360 operation is necessary because If the program ran 
for a long time, the result of DIRECTION [I]+AMGLE could eventually 
e^cceed MAX INT and cause a. run- time error. 

All that rentains is to declare tKe array DIRECTIONj 

DIRECTI0HrARRAY[K,3] OF INTEGER; 

The contplete prograiD begins on the following page* 
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PROGRAM PATtERKS; 

USES rUETL EGRAPH I CS , APPLESTUFF j 

CONST 

C^MaxisuiQ yL and Y coDrdlnAEee*) 

MAXX*2a0| HAXY-lSl; 
(*RadluB of pattern*) 

RABlUS-95; 

TYPE 

(*rhlH type stores one aet of screeo coordinates*) 
POINT-RECORD XjB.^MAXX; 
Y:ia,.HAX¥ 

END J 

VAR 

C*Counter far how mfiny tiraefl trlaagle has been rotated back to its 
Initial poBlcion*) 

CYCLES:0*.2; 
C*AngIe for rotating triangle*) 

rHETA:3..L5j 
{*Array ta store coordinates of comers of triangle*} 

TaCLtAHRAY[l,,3J OF POINTj 
(•Index for comers of triangle*) 

C*Polnt to atore coordinates of one corner of triangle, before any 
rotatlona*) 

CORKER: POINT J 
(*Palnt to store coordinates of center of acreen*) 

CENTER: POlhIT; 
C*Array to store direction angles used to generate triangle*) 

DrHECTI0N;^RAT[l,.3J OF INTEGER; 

PLTNCTION ARBITRARY <LOU, HIGH: INTEGER): INTEGER; 

(•Returns a paeudo-randoni Integer In tKe range LOW through HIGH. This 
function should only be [:alled with constants as parameters. HIGH must 
be strictly greater than LOW; it muat not be equal to LOW. Also the 
difference betveen HIGH and LOW must not exceed HAXINT.*) 

VAR MX, Z, D: INTEGER; 
BECIM 

Z:-HIGH-LOW+lj 

MX:-(MA^INT-HIGH+L0U> DIV Z+Ij 

MX;-MX*(HIGH-L0W)+(MX-1) i 

REPEAT D: --RANDOM miTlL D <- MX; 

ARBITftARV:-LOW+B MOD Z 
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/«*««***#**************************************************************) 

PROCEDURE MAKETRGL; 

f*Make a triangle, defined by three randomly choseti points at a distance 
RADIUS from the point CENTER. Choose each point hy starClne at CENTE.R, 
turning to a random anfile, and moving the distance RADIUS* Store the 
angles in DIRECTION, the point coordinates In TRGL, and the third point 
(for future reference) In GORWER. Motlce how conveniently this Is done 
by moving the turtle around with the color NONE**) 

VAR I; I*. 3; 

PENCOLORCNONE); 

FOR I:-l TO 3 DO BEGIN 

MOVETO (CENTER. K, CENTER, Y)j 
DIRECTION ill :-AB.HITRARY(0. 359); 

TURNT0(D1RECTI0H [I] ); 
HOVE (RADIUS); 

TRGL 1 1 1 . X : =TUKTLEX ; 

TRGL ( I 1 . Y : -TURTLEY 
END; 

CORNER . K : -TURTL EX j 
CORNER. Y:°TUKTL EI 
END; 

FRJOCEUURE ROTATE (ANGLE: INTEGER); 

(* Rotate tho triangle defined by point coordlaateS in TRGL and angles In 
DIRECTION, by adding ANGLE to the angles In DIRECTION, taking the 
result HOD 360,, and using cht^ge angles to determine Che new corner 
coordinates. Again the turtle is looved around using the color NONE.*) 

VAR Iil,.3; 
bEGtN 

PEWCOLOR{MONF.); 

FOB l:=l TO 3 DO BEGIN 

MOVKTOtCENTER.X, CENTER.Y); 

DLREt;TlOW[Ili=(DIRECTIONtIJ+Al]GLE) MOD 360; 
TORNTOCDIRECTIOM [1] ) ; 
MOVE (RADIUS); 
TRGLU1.X:=TURTLEX; 
TRGL[X].Tf;=TURTLET! 
ENL 
END J 
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(*H3ln Frogram*) 
BEGIN 
(*Do iaitializatiitna that will not need tQ be: repeated*} 



HAHDUMlZEi 

iNITTUEtTLE; 
CENTliR.X:-TURrLEX; 



CENTER. Y:-TURTLEY; 



(*To get a different sequence each time 

pro^raro is exetuted*) 
(*AlwayB do thlB to use TURTLEGRAPHICS*) 
{*The turtle Is at the center becfiuee 

INITTURTLE leaves it there. Save Ita 

coordinates In CENTER**) 



(*The following (Qtiter) REPEAT statement creates a new triangular 
pattern each time through**) 

REPEAT 

MAKETRGL; (*Make triangular pattern*) 

TKETA:-AltBltRAllY(3. 15); (*Choo9e angle for rotating triangle*) 
C¥CUS;-tf; (*Clear the cycle counter*) 
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(*rhe follcswlne (Inner) REPEAT atatement draws the triat^le In a new 
rotated position each time through.*] 

FEPEAT 

{^Rotate the triangle**) 

ROTATE(THETA); 

(*Drav the tfi&ngle- This Is conveniently done with Cartesian 
graphics, eirtce the coordinates are all set up.*3 

PENCOLCSE (REVERSE); 

FOR C:^l TO 3 DO MOVETO(TRGL[C] -X, TRGL|Cl.Y); 

{*Kow, If Che third comer of the triangle luatches the CORNER velue 
saved earlier (by MAKHTRGL) , then the trlar^gle has been rotated back to 
its oTlglnal position.*) 

IF TRGLp]=CORWEH THEM CYCLES ! -CYCLE S+ 1 

(*End the repetition If the triangle has returned to Its orlglnfll 
position twice. When this Is the case, the pattern has been erased hy 
being drawn over with the REVERSE color.*) 

UWTIL CYCUS-2 

C*End the outer REPEAT atatetDent when a key is pressed-*) 

UHTIL KEYPRESS 

EfJD. 
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OTHER DEMONSTRATION PROGRAMS ^ 

A sec of demons cradjon progranis 13 supplied with the Pascal Syatem. 

Althoagh theae prograEoa az^ not fully annotated, Chey are worch carefLiJ. S 

study by ajiy acudent of Pascal* The followlna are brief descrlptlana of 

the programs . ^^ 

The *TEXT version of each program has been included on diskette APPLE3: __ 
EO Chat you can read the progratn'e cext into the Editor, to see how the C 
progcaro was written and to try inodlf icaclons of your dhti* 



DISKEHE FILES NEEDED 

The follotfing diskette files allow you, to execute the various 
deiDonBtratlon programs. The ndtatlon xxxjHcx standB foe Che nacje of a 
particular deDionstralon program. 



B 
6 



kxxxx:k*c;0DE 
SYSTEM.LIBRMY 
SYSTEM. CHARS ET 



{any diskette, any delve) 
(boot diskette, boot drive) 
(arty diskette, sny drive; required 
if tfCKAR or WSTRING used) 



Ore-drive ndce: Use the Filer Co Kransfer the dealred denian^tratlon 
program's -CODE file to your hoot diskette, APPLE(i): or APPLE!;. Then 
you can X(ecute the program with the boot diskette in the disk drive* 

Multi-drive note: You should place your boot diskette. APFLE0: or 
AFPLEl ! , in the hoot drive- The demonstration programa are all 
normally found on diskette APPLET:. With APPLl!:3: in any available disk 
drive, you are ready to X(ecute the demons t rat ion programs- 

If you Just wish to e:H:a[nine the text version of a deoionstratlon program^ 
there are two ways to proceeds 

- For a quick look, put diskette APPLE3: in any available drive, 
and then use the Filer to T{ransfer the desired proeratu'e 
,TKXT file frora APPLE3: to CONSOLE:, To atop the program's 
listing on the screen, preas CTRL-S* Preaa CTTRL-S again to 
contlflue- 

- To examine the text In more decall^ you can E(dlt the 
program'a -TEXT file- On one-drive aystoms, first use the 
Filer to T<raa9fer the program's -TEXT £lU frora APPLES: to 
your boot diskette, APPLET; or APPLEl:- Then E(dlt the file. 



» 



120 APPLE PASCAL LANGUAGE 



3i 
si 

a 
-a 



If you wish to modify, cotiqslle, and execute a nev version of a 
denQaetratlon programj th& following dlskfllea will be needed: 



xxxxxx.TEXT 

SYSTEM- EDITOR 
SYSTEM-COMPILER 
SYSTEM- SYNTAX 

3YSTEM*PASCAL 
SYSTEH-LIBRAHY 
SYSTEM. CHARS ET 



(any diskette, any drive; 

required only until read Into E^icptr) 
(any diskette, any drive) 
(any diskette, any drive) 
(boot diskette, any drive; optional 

Compiler error messages) 
(boot diskette, boot drive) 
(boot diskette, boot drive) 
(any diskette, any drive; required 

If WCHAH or WSTRING used) 



One-drive note: Diskette AFPLE0! normally contains all the needed files 
except Che denonatration program's -THXT file. You should use diskette 
APPLE0: as your boot diskette, and TCransfer the desired demonstration 

program's -TiiXT file to AFFLEi>!* Then, with APPLET: in Che disk drive, 
you are ready tg E(dlt and K,(un the program- 

Two-drlve note: Using diskette APPLE(i: aa your boot diskette, put 
APPLEiS: In the boot drive and put APPLE3J in the other drive. You ara 
then ready to E(dlE and RCun any program's *TEXT file on APPLE3:. 



THE "TREE" PROGRAM 

TkEli shovs the creation of an unbalanced binary tree to sort aud 
retrieve data elecnentis (words. In this caae) . It lets you specify each 
new word to be stored in the cree^ and then shows you graphically just 
where the new word was placed In the tcee- 

When you X(ecute TREE-CljE, you are pronipted to 

ENTER WORD; 

To quit the program at any time, ygu can just press the RETURN key In 

respoQse to this message. To continue, you should type the first word 

to be sorted {only the first six charactera are u^ed). For example, you 
might type: 

FLIPPY 

The program then lists the words entered so far, In alphabetic order- 

THE WQKDS DJ OiLDER ARE; 

FLIPPY 
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Ko proDqutinB Titessage appears j but you must now press ch€ RETUItN; key to 
proceed. When you da, a hlgh-reeolution picture Is displayed, showing 
the binary tree as it nov exists. 

BIKARY TREE: 



FLIPPY I 



V 
\ 

The box repros^nts the binary tree's first "node", or sorting clenienc* 
The node has two "links" which can point the way to further iiodes: the 
upper link In thE display can point to nodes which precede thla nod© 

alphabetically, while the lower llofc can point to nodes which follow 
thla node alphabetically. 

To continue, press the RETURK key again. Aga,ln you are prompted to 

BNTER WORD; 
Suppose you now type 

APPLE 
The progran reapoads 

THE WORDS IN ORDER ARE: 

APPLE 
FLIPPY 

and when you press the RETUHJS key, another picture of Che tree Is 
displayed * 

BttlAaY TREE: 



m 
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This is how the word APPLE is placed In the binary tcee* The word APPLE 

Is compared to the wocd In Che first node, FLIPPY. Since APPLE precedes 
FLIPPY, alphabetically, the search continues by follovlng the first 
node's upper link* If another node is found at the end at that link, 
APPLE Is conpared Co the word in that node, and the search continues by 
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Eallowlag thst node's appropriate link. The search contlnuea until, on 
following an appropriate Link, no node is found witli which to compare 
APPLE, At that point on the tree, a new node la created, containing 
APPLE, 

Retrieving the vords to list them in alphabetic order is harder to 
deacrlhe, although the algorlchiii la fairly slinple, 

L. Starting at the root node, FLIPPY, Eollow the tree taking only the 
upper link frora each node, until a node is found whose upper link 
doea not connect to a. further node. The wotd In this node ia the 
first word„ alphabetically, so print it, 

2. Mow follow this node's lower link. 

a. If a node Ifl connected to the link, follow the tree taking only 
the upper link froDi each node, until a node Is found wlioge upper 
link does not connect to a further node. Print that node's word 
as Che next one in alphabetic order, and repeat step Z. 

b* If no further node is connected to the link, go back down the tree 
to the node whose upper link led to this node. Print that node'a 
word as the next one in alphabetic order, and repeat step 2. (If 
no link or a lower link led to thla node, the Hat is coniplete.) 

Reiiieraber, to quit this program just press the RETURW key In reaponse to 
the Desffage 

ENTER hFOEfi: 

Caution: You must pretes the RETURN key two clmes between eack word entry 
(whether or not you wish to aee the tree diagrapvned). But If you 
accldentalli^ press RETUHH three times, the prograia 1b terminated and 
your list la lost forevt.r. 

Program TREE contains exan^les of the following: 

I. InBcrting elements into an unbalanced binary tree (INSERTIT) 

2- Retrieving elements In order from auch a tree (PRINTTREE) 



THE "BALANCED^' PROGRAM 

BALAiiCED is Identical to TREE, except that ft stores words by creating a 
balanced blnacy tree. It ia taken froi an example shown on page 215 of 
the book "AlgorlEhma + Data Structures ' Programs", by Nlcklaus Hirth 
(Prentice-Hall, 197&). An AVL-BALANCED HINARY mEE is rearranged after 
each element Insertion to ensure that, of the two branches at any node, 
one brancti is at most one node longer than the other branch* This 
method of element insertion is slower chan for an unbalanced tree, but 
subsequent retrieval of elements is faster. 
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Re^d the description of the TREE demons crat:Loti program for deCalls about 
USlng^ this program^ Ne^W uords sire added to the BALANCED tree In the 
same way described for the unbalanced TREE, but tbe rearrangeinent of the 
BALANCED tree followlnE an insercJon ie more complex. The words arQ 
retrieved In alphabetic order idenclcaily Iti the two programs* 



THE "CROSSREF" PROGRAM 

CROSSREF is an example of a textual cross-reference generator using an 
unbalanced binary tree to Store and sort words. It le taken from an 
example shown on page 23b of the book "Algorltbrae + Data Structures ^ 
Programs", by MlcklauH Ulrtli tPrentice-Hall, 1976). 

Vheu you XCecute CROSSElEF.CODEt you are prompted for the name of an 

INPUT FILE? 

Respond by typing the filename of a. ceKt file that you wish croes- 
referenced, on any available diskette. It is not necessary to specify 
tbe f 1 le na me ' B ^TRXT suff ix^ For ex^cnple, you night type 

APPLE(J:MYSTUFF 

The program then prompts you to specify a 

DESTINATION FILE? 
for the resulting cross-referenced list* Vou should re-spond by typing 

CONSOLE: 
if you want the list Co appear on the screen* or 

PRINTER: 

if you want the list to be printed on your printer Cwhlch fBuat be 
counecteii and turned un)* 

Firsts Che INPUT text file Is displayed an the screen or printed, with 
each line of text nucnhercd' Ths words of the text are then stored in 
alphabetic order In a binary tree, one word to eath node' A word is 
defined as beginning with an alphabetic character and containing all 
subsequent characters until the next nan^cJlphanunieric character* 
Finally, the text's words are displayed or printed in alphabetic order, 
each word follawed by the text line numbers li^ere that word appears. 

Progian CROSSREF contains exatnples of Che folloving: 

1. Set membership (tVFG defines Itens af the tree structure} 

2- Sorting Into a binary tree 
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3. Listing from a binary tree (PRIMTTREEj, also shows recursion) 

For loore informaElon abnut tree-sorting, see the demonstratlan progranis 
TREE Bixd BALAKCED* 



THE "SPIRODEMO" PROGRAM 

SPIEIODEHO demonstrates the basic TUELTLEGRAPHICS inaneuver: move the pen 

in a straight line, turn, move again in a straighr Line, turn again, and 
ao on. 

The progras) Ista you specify an ANC^LE and a CHANGE p and then draws a 
pattern on the screen- To make tho pattern, SPIRODEMO moves the pen one 
unit* turns through ANGLE* radves l-HCHANGE, turns ANGLE, moves 

l.-K:HANGE-H:HAKt;E, turns ANGLE, etc, 

Vfbea you X<ecute SPXRODEMOfCODE, this message appears: 

WELCOME TO WHLLEPLOT 
ENTER ANGLE TO QUIT. 

ANGLE: 

If you wish to leave the program at any time, Just wait until this 
pron^ting message is displayed, and Chen respond by typing a zqto and 
pressing the RETURN key. If you want to continue, typo any positive or 
negative Integer to specify the angle (in degrees) through which you 
wish the TURTLEGRAPHICS pen to turn between each move- Far exaiq3le, you 
might respond by typing 

89 

This tells the pen to turn clockwise, slightly less than a right angle 
between each movei Now you are asked to specify a 

CHANGE : 

Starting with a atralght-line pen edovc of one unit* each eubaequent move 
will increase in length by an omaunt specified by CHANGE- You must 
respond by typing a poal Cl YC integer graa ter than zero . For exaiop le , to 
make each line one unit longer than the previous line* you would type 

L 

When you press the RETURN key, program SPIRODEMO (alias WHILEPLOT) 
begins CO draw ita design on the screen, using the parameters that you 
specified* 

On CDrapletion □£ the design, the prograia continues to display the dssign 
until you press any key on the Apple's keyboard. Just prese the Apple's 
spacebar, and the original prompt message will replace the design on the 
screen. You are then ready to specify a new CEAUGE and DISTANCE for 
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another deBlj^n (or specify an ANGLE of zero to qtilt the program). 

Caucion: This pfoBram dlEa If the first character of an ANGLE or CBAI4GE 
response is qqi: a pXus sign, a niinus sign^ or a numeric dlglt- 

Frogram SPIRODEMO cantalns eiKaiopXeB of the following: 

K Using the TURrLEGRAPUICS unit. Including the KEYPRESS function 

2* Reading the keyboard buffer vlchout echoing on the screen 



THE "HILBERT" PROGRAM 

UILBERT shovs an historically famous example of recursion, uBlng a 
spaae-f illlng design to create an atcractlve display on the screen* 

You can determine Che density of the space-filling design by specifying 

an Integer ORDER from 1 through 7. 

When you X(ecute UILBtlRT pCODE, thia me^as,^e appears; 
EWTEk ORDER TU QUir. 
ORDER: 

If you vrlsh to cjulL the program at any tlmep Walt until this message 

appearSi and then type a siero* If you wish to continue^ you ntust type 
an Integer frnm 1 through 7* Ar ORDER of I fills the sp^ce ntost 
"lpgsely'\ taking barely one repetition of the design to fill the 
screen- Eacli higher order £111.3 the screen uure and loore deosely, by 
repeating the basic design on a sccaller and smaller scale. Order 7 
fills the screen to solid white, and takes quite a long Elrae doing It- 
Thtre is no way to stop a dl&play while It Is being created, except to 
pr&ss the RESET key. To get the Idea, respond by typing 



On completion of the design, the program continues to dlsplajr the design 
until you press any key on the Apple's keyboard. Just press the Apple's 
apacebarp and the original prompt nyessage will replace the design on the 
screen- You are then ready to apeclf y a new ORDER for another design 
(or specify art ORDER of zero to quit the prograns). » 

Caution; This prograiD is terminated If the ORDER response is not a 
nuneric digit from 1 through 7. 



THE "GRAFDEMO" PROGRAM 

GRAFDEJ'IO Is a collecLlon nf Interesting 

a tiumDer of very useful procedures- 
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The prograp runs without any Interaction; juat watch the pretty pictures 
and then study tiRAFDEMO * TEXT to see examples of how thesie things can be 
done using TtTKlLEGRAPHICS- ¥ou may even find It handy to uae some of 
GRAJTDEMO's procedures directly, in your own programs* 

When you X(ecute GRAFDEMO. CODE* this unusual meseage appears: 

PRESS ANT KEY TO QUIT* 

PLEASE WAIT WHILE CREATING EUTTERFLY 

Just wait; soon you will see butterflies and many other graphical 
marvels* PreBsing any key on the Apple keyboard will terminate this 
program on campletlon of whichever display Is currently being created* 

Program GRAFDEMO contains examples of the following: 

1. Using TURTLEGRAPHICS to draw frames, crosBhatchlng, etc* 

2. Creation of an array (BUTTER) for use by procedure DRAWBLOCK 

3- Handling of a procedure chat Is coo longj by breaking it Into smaller 
partEi (BUTTER) and calling those parte from another procedure 

(IWITBUTtBR] 



THE "GRAFCHARS" PROGRAM 

GaATCHARS 3hoW9 the characters found In Che file SYSTEM^CUARSET, and 
their use from TURTLEGBAFHICS * The program runs without Interaction* 

When you X(ecute GRAFCHARS .CODE , this mesaage appears: 

PRJESS RETURN FOR MORE*»» 

From here on* each time you press the Apple's RETURN key another display 

Is placed on tbe screen' The first display shows all the characters 
available In SYSTEM. GKARSET . Wlien you have examined any display to 
your aatl&factionj just press the RETUBW key again to go on to the next 
display* 

Program GRAFCHARS contains examples of the following: 

i. All the upper-case, lower-case, and special characters available 
through TURTLEGRAPHICS 

2- Use of TURTLEGRAPHICS" WCHAR and WSTRING functions 

3. How to pu: a border around a string (BOXBTHING) 

4- Use of CHARMOCE to keep the characters' boundaries from interfering 
with the background 
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THE "DISKIO" PROGRAM 

PI3KID shows a sample use of randont-access disk files, wich terndnal- 

indep>£Ddent output' 

Not^: This program is NOT a real application, and It I3 definitely MOT a 
data-base laanager* lL& only purpose Is to demonstrate some Qf the 
principles that would be Invalv&d in writing a real flie-handilng 
program. 

When you X(ecute DISKIO. CODE, you are asked to specify a 

FILE NAMEr 

You should typs a valid disk-file Identifier* For example, you tolght 
respond b)r typing 

APPLET : MYF ILE -TEKT 

The program looks on the specified diskette (or the default diskette) 

for a file with the specified filename* If an existing file by that 
name Is found, IL Is opened and the loaln program coinmand prciqipt line Is 
displayed- l£ no file by that naiae la found, Che prograsi eaks if It 
should 

START A NEW FILE? 

If you type H lot No, you will again be aaked to type a FILE NAME, 
There is no exit from the program at thia point except by auccesafully 
opening a file or hy pressing the RESET key. If you type Y for Ves^ the 
program asks 

RESERVE HOW MANY RECORDS'? 

Respond by typing an integer that specifies the number of records your 
new file will initially tontain. For example, if you type 



your new file will Start out contfllttlng seven records, nunbered fl 
through 6* 

Now the program's oaln couniand pro&^t line appeara on the screen: 

V{IEM C(HANGE NCEXT FCILE QtUIT 
Typing a V for V (lew causes this message tc appear: 

VIEW WHICH RECORD? 



Hi 
9 
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You ahould reapond by typing a nutnber from zero through the niaxirauni 
record nmi^er in your file. For instance, typing 



letfl you view the contents of record nuinher 5, 

If you then wish to view Che contents of the next record, type K for 
M(exC> In this way, you can look at as utany rscords as you wish. 

Typing a C for C(hange causes this niessage to Appear; 

CUAflGE WHICH RECORD? 

Agaln^ you should reapond by typing a tiumber from zero through the 
maxlDiuaL r&coi:d Qumber In your file- For instance, typing 



lets you change the contents of record nuisber 5. To change an entry. 
Just start typing. To leave an entry as It la, and go on to the next 
entry, just press the RETURS key* 

If you then vlsh to change the contents of the next record, type N for 
N{ext. tn this way, you can change as many records as you lidsh. 

If the NCext command takes you beyond the last record specified for your 
file, the program will attempt to extsnd the file by appending 
additional records^ Ihia is possible if 

1' there Is room for the record In the current laac block of the file. 



2. the next contiguous block on the diskette is available for use by 
this file- 

If ic la not possible to extend your file, a iDessage appears to inform 
you of the problem. You can then type Q to Q(ult thla prograni, enter 
the Filer, and nsove files on the diskette until your file has a few free 
blocks immediately following It* (Use Che Filer's ECxtended List 
comLuand to see the locations of free blocks,) Then you are ready to 
X(ecute DISKIO again, and extend your file with additional records. 

Typing F for F(lle, In response to the main cOnnnand pCOnrpt line, lets 
you start a new file or reopen another old file- As at the beginning, 
you are asked for a 

FILE NAME: 

Again, there Is no exit from this part of the progran except to give a 
euccesaful fllenatne or to press the RESET key. 
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Prograo DISKIO contains example3 of the following: 

1. TBrniaal-ln dependent output, by reading the file 5TSTEM,MISCINF0 and 
uelag the teirminal secup parameter^ found there (GETCRTINFO) 

2. Euilfit-proof character input (GETCHAJl) 
3- Bullet-proof string input, with defauXta 

4. Use of raodoni-access disk flies and syateiti procedure SEEK 

5. Hgw La extend a diskette file in place- 



^^ 
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APPENDIX B 

TABLES . 



Table 1: EiiecutloTi Errors 

Table 2: I/O Errors (lOHKSULT Valuas) 

Table 3: Reserved Words 

TAble *i Predefined Identifiers 

Tablp 5: Identlfiera Declared In Supplied ITNTTs 

Table b: CompHer Error Hesaagea 

Table 7: ASCII Charactec Codes 
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TABU 1: 
EXECUTION ERRORS 



FATAL 



11 

12 
13 
14 
15 



System error 

Invalid index, value out of range (KBiVNUX) 

No EegmeiiC, bad code file (KNOPROG) 

Procedure not present at ejcit time (KNOEXIT) 

Stack overflow {XKIKOVR) 

Integer overflow (JtlNTOVH) 

Divide by zero tKDIVZER) 

Invalid memory reference <h\iB ciraed Dut> fXBADHEK) 

User break (XUBREAK) 

Syateoi L/0 error (XSYIOER) FATAL 

User I/O error (XUIOERR) 

Unlmpleraented instruction (XNOTIMP) 

Floating point math error (XrPlERR) 

String too long (XSZLONG) 

Halt, Breakpoint (vlthnut debugger in core) <XHLTBPT) 

Bad Block 



All FATAL errors require that Che syatem be rebooted- In some cases the 
aysteiQ will reboot autamatlcally, and In other cases you villi have Co 
reboot it. All other errors cause the system to re-'inl tlalize Itself, 
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TABLE 2: 

I/O ERRORS (iORESULT VALUES} 



No error 

1 Diskette has bad Block: parity error (CRC). 

{Not used on the Apple.) 

2 Bad device (volume) Number 

3 Bad Mode: Illegal Dperatlon. (For exatnplej an 

attempt to read from PRINTER:-) 
^ Undefined hardware error* (Not used on the Apple*) 

5 Lost device; device is no longer oTi-linej after 

successfully HCartlne an operation uislng that 
device ■ 

6 Lost file; file is no longer in Che diskette 

dlrettcry, after succGasfnlly etartng an 
operation using that file- 

7 Bad title; illegal file naioe* (For exati^jle, 

filename Is more than 15 characters long*) 

8 Ho room: insufflclenc space on the specified 

diskette* (Files must be stored in contiguous 
diskette blocks. ) 

9 No device: the specified volume is not on line 

10 No file: The specified flLe is not in che 

directory of the specified volume* 

11 Duplicate file: attempt to rewrite a file when 

a file of thaE name already exists- 
IZ Not closed: attempt Co open an open file- 

13 Not open, attempt to access a closad flle- 

14 Bad fortnat, error In reading real or integer- 

(For exantp le , your program expec^ts an Integer 
input but you typed a letter,] 

15 Ring buffer overflow: characters are arriving at 

the Apple faster than the input buffer can 
accept them* 

16 Wrlte-protect error: the specified diskette la 

wrl te-protected- 
64 Device error; failed to complete a read or write 

correctly (bad addreea or data field on diskette). 



See Chapter 3 for description of the built-in function IORESULT* 
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TABLE 3: 
RESERVED WORDS 



These are words that have fixed meanlnea in Pascal* Tou can never ue« 
them as Identifiers uichout causing a compiler error. The next two 
tables list some more words you shotild not use as identifiers. 



STANDARD PASCAL 
RESERVED WORDS 



AKU 
ARRAY 

BEGIN 

CASE 

CONST 

DIV 

DO 

DOWNTO 

ELSE 

Eim 

FILE 

FOR 

FORWARD 

FUNCTION 

GOTO 

IF 

IN 

LABEL 



MOD 
STL 
SOT 
OF 

(m 

PACKED 

FEtOCEDURE 

PROGRAM 

RECORD 

REPEAT 

SET 

THKN 

TO 

TYPE 

UNTIL 

WAR 

WHILE 

WITH 
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RESERVED WORDS 



EXTERNAL 

IMPLEMENTATIOlfl 

INTERFACE 

SEGMENT 

UNIT 

USES 



^ 


4 


E 


51 


& 


^ 


K 


:-« 


& 


!i 


^ 


^ 


fe 


^ 


m 


'■a 


^ 


^ 


^ 


4 


1 


3 


E 


3 


i 


4 


E 


3 


s 


4 


m 


4 


E 


^ 


■ 


^ 


■ 


H 


E 


3 


m 


a 


m 


if 


^ 


1 ^ 



TABLE 4: 

PREDEFINED IDENTIFIERS 



These are the identifiers of the bulIt-ln procedures and functlona and 
the predefined, types and variables of Apple Pascal* The list does nat 
include thoae identifiers that are declared or defined In the special 
UNlTs aupplled for the Apple {see next table). If you declare or define 
one of these Idenclflera In your prDgE^ara^ no exror will result but yoa 
will lose the capability of the corTeaponding built-in or predefined 
entity. 

With each identifier, a code Is shown In (brackets) to indicate what 
kind of object the Identifier repreeents* The codea are 



{p> FROCEDtmE 

{b> liOOLEAB FUNCTIOS 

{t} TYPE 

(k> CONSTANT 

(a) STRING FUNCTION 

ABS {r> 

BLOCKREAD (i> 
BLOCKWRITE {1} 
BOOLEAN {t> 
CHAR <c> 
CHK (c> 
CLOSE tp> 
CON CAT <a) 
COPT <s> 
DELETE {p> 
EOF <b> 
EOLN {b> 
EXIT (p> 
FALSE <k> 
FILLCHAR {p> 
GET {p> 
GOTOXY <p> 
HALT <p} 
INPUT {£> 
INSERT {p> 
rKTEGER {1} 
INTERACTIVE <t) 



{1} lEJTEGER FUNCTION 
{r> REAL FUNCTION 
{c> CHAR FUNCTION 
{£} FILE 
{-> OTHER 

lORESlTLT {i> 
KEYBOARD <f} 
LENGTH ii) 
MARK {p> 
MAXINT (k> 
HEMAVAIL {i> 
MDVELEFT {p> 
MOVEBtCHT <p> 

NEW <p> 

ODD (h) 

ORD {!> 

OUTPUT <f> 

PAGE {p> 

POS <!} 

PRED <-> 

PUT Cp> 

PVROPTEN <r> 

READ {p> 

READLN <p> 

REAL {t> 

RELEASE (p> 

RESET {p> 



REWRITE {p> 
R0UNT5 <1> 
SCAN {1} 
SEEK <p} 
SIZEOF {1} 
SQR (r> 
3TR (s) 
STRING U) 
SUCC {-} 
TEXT {t> 
TREESEARCH (1) 
TRUE <k> 
TRUNC {i> 
UNITBUSY {by 
UNLTCLEAR <p> 
UNITREAD {pj- 
ONITWAIT {p> 
ONITWRITE {p> 
WRITE {p> 
HRITELN {p> 
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TABLES: 

IDENTIFIERS DECLARED 

IN SUPPLIED UNITS 



These idenclf lers are effectively declared or defined only IE your 
prograiq USES their reapecclve UNITs. If your program USES a UNIT find 
you atci^iopt to declare qr define One of the identifiers belonging co 
that UNIT, you will get a compiler error inesaage 16S1; "Ideiitif ler 
declared twice." Hovever If your prograti doesn't USE a particular UNIT 
you can make free use of the Identifiers of thac UNIT, 

With each Idei^tlfier, a code Is shown in (brackets) to Indicate what 
klad of object the Identifier repreaents. The codes are 



{p} PROCEDURE 

ib} BOOLEAN FUNCTION 

<t> TVPE 



TURTLEGRAPHICS UNIT 

CHARTYPE <p} 
DRAWBLOCK {p} 

FILL SCREEN {p> 
GRAFMOLE {p> 
INITTURTLE {p)- 
HOVE {p> 
MOVETQ <p> 



APPLESTUFF UNIT 
BurroN (1) 

KEYPRESS (b) 

NOTE {p> 
PADDLE {1} 



TRANSCEND UNIT 

ATAN {r} 
COS {r} 
EXP <r} 
LN <r> 



Uy IMTEGCH FUNCTION 
(r> RML rUNCTION 



* i 

■ i 3 
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PEKCQLOlt Cpy 

SCREENBIT {b> 
SCREEN COLOR {t> 

TEXTMODE {p) 
TURN {p> 
TURNTO ip) 
TURTLEANG {1> 



TURTLES {1> 
TURTLE Y (1) 
VIEWPORT {p} 
WCliAa {p} 
WSTRING {p> 



RANDOM {!> 
RANDOMIZE <p> 

TTLOUT {p> 



LOG {r> 
SIN <r) 
SQBT <r> 
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TABU 6: ^ ^ 

COMPILER ERROR MESSAGES 



■ 


:§ 


1 
2 






3 


■ 


3l 


4 
5 


■ 


3 


6 
7 


m 


a 


8 

10 


^ 


i 


11 

L2 


E 


3 


13 
U 
15 


■ 


^ 


16 
17 


■: 


^ 


18 
19 



When the Pascal Coiopllsr discovers an error In your program, it reports 
that error Immediately, by error number. If you then enter the Editor 
to fix that error, a Tuore complete error meesage is glvenj taken from 
the boot diskette file SYSTEM. SYNTA.K . If you remove the file 
SYSTEM. SYNTAX froni the boot diskette, errors will be reported by number, 
only* 

The Pascal Compiler error message cortespondlng to each error number is 
given in the table below. Some people will prefer to gain some 
additional space on their boot diskette, by removing SYSTEM. SYNTAX and 
using this table instead* You can also print your own copy of this 
table by transferring the file SYSTEM. SYNTAX to a printer. 



Error In simple type 

Identifier expected 

'PROGRAM' expected 

') ' expected 

' : ' expected 

Illegal symbol (possibly missing ';' on line above) 

Error in parameter list 

"of' expect Gd 

'^C expected 

Error in type 

' (' expected 

'1 ' expected 

'end' expected 

';' expected (possibly on line above) 

Integer expected 

""' expected 

'BEGIN' expected 

Error in declaration part 

Error In <fleid"llst> 

'*' expected 

'*' expected 

'interface' expected 

'Implementation' expected 

'Unit' expected 

Error in constant 

': ■' expected 

'THEN' expected 

'UNTIL' expected 

'DO' expected 

'TO' or 'DOWNTO' expected In for aLatement 

IF expected 
'FILE' expected 

Error in <factor> (bad expression) 
Error in variable 



21 
23 



51 
52 
53 
54 
55 
56 
S7 
58 
59 



101: Identifier declared twice 
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102: Low bou nd exc e e d s hi gb bo'Und 

tti3: Idencif ler is not of Che appropriate claaa 

l^^z Undeclared Idencificr 

105; Sign not allowed 

1(^6' Number expected 

107: Inccompatible subrange types 

10^: File not allowed here 

109: Type imist not be real 

110; <Cagfleld> type muBt be scalar or subrange 

111: Incompatible with <tagfleld> part 

112: IndeK type miat iiot be real 

113; Index type must be a scalar QF a subrange 

11^: Base type miifiC not be real 

115: Base type must Ise a scalar or a subrange 

llbi Krror In type of standard procedure parameter 

117: Unsatlefled forward reference 

116: Forward reference type Identifier In variable declaratlDn 

119: R-e-^speclf led parameters not OK for a forward declared procedure 

120: Function result type nust be scalar, subrange or pointer 

121: File value parameter not allowed 

122: A forward declared function's result type can't be re-apeclfled 

123; MlsslnE result type In function declaratioci 

124; F-f ormflt for reals only 

125: Error In type of standard procedure parameter 

126: Number of parameters does not agree with declaration 

127: Illegal parameter substitution 

126: Result type doee not agree with declaration 

129; Type conflict of operands 

130; Expraaslon is not of set type 

131: Tests on equality allowed only 

132: Strict Inclusion not allowed 

133; File cottiparlsDQ not allowed 

13>4: Illegal type of aperand(s) 

135: Type of operand must be boolean 

1 36 : Set element type mi9t be scalar or subrange 

137: Set element types must be compatible 

133: Type of variable is not array 

133: Index Cype la. not compatible with the declaration 

140; Type of variable is not record 

141; Type of variable niuat be file or pointer 

142; Illegal parameter solution 

143; Illegal type of loop control variable 

144: Illegal type of expression 

145: Type conflict 

146: Aaaignment of files not alloved 

147: Label type Incompatible with selecting expreaaion 

14@: Subrange bounds must be scalar 

149: Index type must be integer 

150: Aflalgnnient to standard fuinctlon is not allowed 

131: Assignment to fortoal function is not allowed 

152; Ho Buch field in this record 

153; T^pe error in read 

154: Actual parameter inust be a variable 

155: Control variable cannot be formal or non-local 



ft 31 

ft ^ 

t ^ 

m ^ 

m ^ 

m j 4 

m 4 

E 3 

1^ -I 

P 4 

E 3 

e ^ 

m M 



56: Multldefined case label 

57: Too many cases In case statement 

■5&1 Wo Such variant in thla record 

59: Real or string tagflelds not allowed 

60; Previous declaration was not forward 

61; Again forward detilared 

62; Parameter sJae mist be constant 

63: Mlasing variant in declaration 

64: Substitution of standard proc/func not allowed 

65: Multldefined label 

66: Wultideclared Label 

67: Undeclared label 

68: Undefined label 

69; Error in base aet 

70: Value parameter expected 

71; Standard file was re-declared 

72: Undeclared external file 

74: Pascal function or procedure expected 

B2: Heated units not allowed 

83: External declaration not allowed at this nesting level 

84: External declaration not allowed in Interface section 

35 : Segment declaration not allowed in unit 

36: Labela not allowed in interface section 

37: Attempt to open library unsuccessful 

88: Unit not declared in previous ' Uses' declaration 

69: '^U^es' not allowed at this nesting level 

90: LTnit not In library 

91; Ho private files 

92: 'Uses' uuBt be In interface section 

93: Hot enough room for this operation 

94: CoisDent mu^t appear at top of prograai 

95: Unit not imporcable 

201: Error In real number - digit expected 

202: String constant must not exceed source line 

203' Integer constant exceeds range 

204: 8 or 9 In octal number 

250: Too taany scopea of nested identifiers 

251; Too many nested procedures or functions 

252: Too many forward references of procedure entriea 

253: Procedure too long 

254: Too many long constants In this procedure 

256; Too many external references 

257: Too many externals 

258: Too many local flies 

239: Expression too complicated 

300; Division by ^ero 

301i Hq ease provided for thle value 

302: Index expreasion out of bounda 

303; Value to be assigned la out of boutida 

304; Element expression out of range 
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350: No data segment allocidtod 

351: Seginent: used tulc€ 

35'2: No code Segment al located 

353: Non*-l n E r i ns le unit called from intrinsic unit 

354: Toe many Begtnente for the seginBnt dictionary 

398: ImplGmentation restriction. 

359: Intpleraentation restriction 

40SJ: Illegal character in text 

4f5l: Unexpected end of Input 

402: Error id writing code file, not enough room 

403: Error In reading Include file 

iS04: Error in writing list file, not enough rocti 

405: Call not allowed in separate procf^dure 

i06; Include file not legal 

407: Too many libraries 
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TABLE 7: 


















A$< 


^\l 


CHARACTER CODES 












K 




















ki 


-d 


Code 


Char 


Code 


Chat 


Code 


Char 


Code 


Char 


m 


:!i 


tlBC 


Hex 




Dec a.^'K 




Dec 


Hex 




Dec 


EEex 







;3d 


HVl 


32 20 


SP 


64 


h% 


@ 


96 


60 


* 






I 


01 


SOB 


33 21 


1 


65 


41 


A 


97 


61 


a 


wt 


! :9i 


2 


02 


STX 


34 22 


H 


£6 


^2 


6 


98 


62 


b 




! -^ 


3 


0^ 


nx 


35 23 


& 


67 


43 


C 


99 


63 


c 


tt 


^ 


4 


04 


EOT 


36 24 


5 


68 


4^ 


D 


103 


64 


d 


5 


35 


ENQ 


37 25 


S 


69 


45 


£ 


101 


65 


e 






b 


06 


ACK 


38 26 


& 


70 


46 


F 


10Z 


66 


£ 


m 


-a 


7 


^7 


BEL 


39 27 


' 


71 


47 


G 


103 


67 


e 






8 


tfd 


BS 


40 2a 


< 


72 


48 


H 


104 


68 


h 


m 


^ 


5 


09 


HT 


41 29 


) 


73 


49 


I 


105 


69 


1 


Itf 


0A 


LF 


42 ZA 


* 


74 


4A 


J 


106 


6A 


J 






11 


;^B 


VT 


43 28 


+ 


75 


4fl 


R 


107 


6B 


k 


m 


^ 


IZ 


0C 


FF 


44 2C 


* 


76 


4C 


L 


I0S 


6C 


1 






13 


0D 


CR 


45 2D 


- 


11 


4D 


M 


109 


6D 


in. 


m 


3 


14 


0E 


SO 


46 ZE 


» 


1% 


4E 


N 


110 


6E 


n 


15 


0f 


SI 


47 ZF 


/ 


m 


4F 





HI 


6F 









17 


10 

11 


DL£ 
DCl 


46 30 
49 31 



1 


80 


50 
51 


P 


112 
113 


70 
71 


P 


g 


M 


<i 






IS 


12 


UC2 


50 32 


2 


82 


52 


R 


114 


7Z 


r 


^ 


m 


19 


U 


DC3 


51 33 


3 


S3 


53 


S 


U5 


73 


B 


U 


14 


DG4 


52 34 


4 


84 


54 


T 


116 


74 


t 






21 


IS 


NAK 


53 35 


5 


^5 


55 


D 


117 


75 


U 


E 


3 


22 


16 


SYN 


54 3& 


6 


S6 


56 


V 


113 


76 


V 






23 


17 


ETB 


55 37 


7 


87 


57 


V 


119 


77 


w 


K 


4 


24 


18 


CAN 


56 38 


8 


88 


58 


X 


120 


78 


X 


■ 


25 


19 


EH 


57 39 


9 


89 


59 


Y 


121 


79 


7 






26 


Ik 


SUB 


38 3A 


J 


90 


5A 


z 


122 


7A 


z 


t 


4 


27 


IB 


Ef>C 


39 3B 


I 


91 


3fi 


[ 


123 


7B 


( 






23 


IC 


FS 


60 3C 


< 


92 


5C 


\ 


124 


7C 


1 


m 


-a 


23 


in 


GS 


61 3D 


a 


93 


5D 


] 


125 


7D 


} 


30 


1£ 


RS 


62 3E 


> 


94 


5E 




126 


7E 








31 


IF 


US 


63 3F 


T 


95 


5F 




127 


7F 


DEL 
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APPENDIX C 

ADDITIONAL DETAI 
OF TEXT I/O 
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ADDITIONAL I/O DETAILS UZ 



HerE are some facts about READ and READLH that you need to know If you 
do not follow the suggestions In the "Introduction to Text I/O" section 
□ £ Chapter 3- lo patLlCDiar, theae facts are Icnportant If you mix 
reading and writing operations on the same diskette textflle' You may 
also need to know exactly when EOLN aod EOF become truE with llEADLN and 
with numeric variables. 

Note that for mixed reading and writing, the rules given belov are more 
straightforward for INTESACTIVE file than for TEXT fllee- 

After READ with a CHAR variable and an INTERACnVE files 

* The file buffer variable contains the character that vas READ, 

unless EOLN or EOF Is true- 

- If the next I/O operation is a PUT, WRITE, or WRITELN, It 
affects the character after the one chat was READ- 

- EOF l3 true If the character READ waa the end-of-file 
character. In this case the value of the file buffer variable 
Is undefined* 

- EOLN Is true if the character READ was the end-of-llne 
character. In thia case the file buffer variable contains a 
space* 

- EOLN is also true if EOF is true. 

After READ with a CHAX variable and a TEXT file: 

- The file buffer variable contaira the character after the 
character that was READ, unless EOLN or EOF is true- 

- If the next 1/0' operation ia a PUT, WHITE, or WRIIEtN,, it 
affects the second character after the one that was l^AD. 

- EOF la true if the character REAB was the last character in 
the file {not counting the end-of-flle character). In this 
case the value cf the file buffer variable Is undefined* 

- EOLN Is true if the character RIAD was Che last character an 

the line (not counting the end-of-llne character). In this 
case the file buffer variable contains a space* 

- EOLN is also true If EOF ia true- 
After blEAD with a numeric variable and a TEXT or INTEEIACTIVE file; 

- The file buffer variable contains the character after the iJSt 
character of Che numeric string that was READ, unleaa EOLN or 
EOF is true. 
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- If the next I/O operation is a FOT, WRITE, or HRITELM, it 
affects the second character after the Last character of the 
numeric string- 

- EOF is true if the last character of the numeric string wag 
the last character in the file {not counting, the end-of-flle 
character)* In this eaae the value of the file buffer 
variable is undefined- 

- EOLN is true If the last character of the numeric strttig was 
the last character on the line (not counting the end-of-llne 
character)- In this ease the file buffer variable cotitalnB a 
apace. 

- EOLN Is also true if EOF is true* 

After READ vlth a STRING variable and a TEXT or IMTERACTI7E file: 

- The file buffer variable contains a apace which represents the 
end-of-llne character at the end of the line, unless EOF la 
true. 

- If the next 1/0 Operation ia a PUT, WRITE, or WRITELN, It 
affects the first character on the next line- 

- EOF Is true if the line READ was the last line in the file- 
In this case the value of the file buffer variable la 
undeflned- 

- EOLN is always true- 
After READLN with any variable and an INTERACTIVE file 

- The file buffer variable coQCalns a space which represents the 
end-of-llne character at the end of the line, unless EOF le 
true- 

- If Che next I/O operation is a PUT, WRITE* or WRITELN, It 
affects the first character on the next line. 

- EOF is true If the line READ was the last line in the file* 
In this case the value of the file buffer variable is 
undef I ned* 

- EOLN la never true. 

After READLH with any variable and a TEXT file 

- The file buffer variable contains the first character on the 
next line, unless EOLN or EOF la true. 

- If the next IfO operation Is a PUT, WRITE, or HRITELN, it 
affects the second character on the next line. 
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- EOF is true If Che line READ was the last line in the file. 
In thlB caae the value of the file buffer variable Is 
undefined, 

- EOLfN Is true only when EOF Is true* 






PENDIX D 



ONE-DRIVE STARTUP 



Equipment You Will Heed 
The Two-step Startup 

Step One of Startup 

Step Two of Startup 
ChengltiR the Date 
Maklnft Backup Diskette Copies 

Why He Make Backups 

How Me Make Backupa 

Getting the Big Picture 

Format tlna Mew Diskettea 

Haklnji Che Actual Cop lea 

Da It Aftaln, Sam 
Using the System 

A Demons t ration 

Do It Yourself 

What To Leave In the Drive 
One-I>rlve Symmary 
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This appendix Is b tutorial aeaalon to get you started using the 
Language Syacera with Pascal, on an Apple II with one diskette drive, if 
your system haa two or taoce diskette drives, please skip thia appendix 
and read Appendl?; E Instead, 



I 
! 4 



I 



EQUIPMENT YOU WILL NEED 



Vou ahould have the following; 

i* Your ^8K Apple coinputer, with & Language Card installed, axid one 
dlak drive attached to the connector marked "DRIVE 1" on the disk 
controller card. The diek controller card laust have the new PROHe, F5A 
and PbA twhicti tiaxne with the Language Syatein), and must he installed in 
the Apple's peripheral device slot 6» 

2. A TV set or video sonltot properly cannecced to your Apple. 

3« The folloving Language Syst>&iii diski^ttes: 

a, APPLES: 

b, APPLEli 
c* AFPLE2: 
d*. APPLE3: 

e. A blank diskette 

f- Another blank diskette 

The diskettes marked "APPLEli" and "APPLEfl : " are needed to start the 

system. The diskette marked ''APPLE2:" adds aorae nxtra features to the 
system (the Aasemhler and the Linker). You will not need the diskette 
marked ^'APPLE2;" until later (many users of single-drive eysteiLS will 
never need it)* The diskette marked "APPLE3;" contains a number of 
useful utility programs ^ and aome Interesting demonstrations j Appendix A 
of this toanual explains these demonstrations. 

Vour Apple and its TV or tncnltoT should be plugged In- Turn on the TV 
rlow„ so that it can warn up J but leave the Apple turned off- 



- "1 



m 
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THE TWO-STEP STARTUP 



3i 



There are two steps to starting Apple Pascal running on your systen 



STEP ONE OF STARTUP 

First insert the diskette marked APPLEl: in the dJsk drive. If you are 
not familiar with handling diskettes, see the mariuala that came with 
your disk drives. Diekettes must be treated correctly i£ they are to 
last. 
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Close the door to the disk drive, and turn on the Apple* The rest of 
Step One Is autoniatit. First, the message 

APPLE 11 

appears at the top of your TV or monitor sctGGiit and the disk drive's 
"IM USE" llfiht comea on. The dlak drive emits a whirring, zickklng 
sound that is as pleasant aa a cat's purring, eince it leta you know 
that everything la working* The streen lights up for an Instant with a 
display of black at -signs t & ) on a white background, then goes black 
^gain. Next, the disk drive stops entirely for a mocnent; then It whirrs 
some more. Finally, che messBge 

WELCOME APPLEl, TO 
U.C-S,D* PASCAL SYSTEM II .1 
CURRENT DATE IS 2*-JUL-79 

appears {the date will be different), followed in a second or so by a 
line at the top of the screen: 

COMMAND! E(DIT, B{UN, F(ILE, C(OMF, L(tN 

This lino at the top of the screen Is called a "prompt line". Wlien you 
see this prompt linej you knou that your Apple computer Is running the 
Apple Pascal systera* 

If you juat wish to edit text and progrsEos, or If you wish to run 
previously compiled prograraa » you may scop now. At this point, your 

system can do most of the things ycu will nornially Wi^nt to do In Apple 
Pascal, except for compiling new programs that you write* 

However^ if you alao wlah to compile programs that you write, in order 
to run ttieicit you should proceed to Step Two of the startup procedure. 



STEP TWO OF STARTUP 

Remove rhe diskette marked APPLEl: from the disk drive, and Insert the 
One marked APfLE^; ■ Close the door to the drive and press the key 
marked RESET , In the upper right corner of the Apple' b keyboard* 

The at-signs come back for an Instant,, and the disk drive whirrs and 
completely stops for a second, then ii^irrs some ouire ■ The whole process 
takes about 16 seconda' Finally, che message 

WELCOME APPLETS, TO 
U*C,S.D. PASCAL SYSTEM II. I 
CUHHENT DATE IS 26-JUL-79 

appears (the date will be different), followed in a second or so by the 

prooipC line at the top of the screen 



COMMAxNI): ECDIT, R<irN, F(XLE, CJOMP, L{IN 
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Again, this procipt lln& lets you knov Chat your 
running the ^ple Pascal System. 



)le coni|>uter la 



After completing Step Two of the startup proceaure, your systein can do 
all the thlnga you will normally want to do in Apple Pascal: filing 
editing, running.*,, and coEiplllng, However, diskette APPLE0: is missing 
one file that la needed for the initial startup when you flrat turn the 
Apple's power on. Thoc la why you mist go through Step One of the 
startup procedure befora going on to Step Two, 



CHANGING THE DATE 



The dace that comes on the diskette will not he correct. It Is a good 
habit to reset the date the first time you use the Apple Pascal System 
on afly given day» It only takes a few seconds. Press F on the keyboard 
(without pressing the RETURK key or any other keys). The screen goes 
blank, and then this line appears at the tops 

FIL£R: G, S, N, L, R, C» T, D, q 

This is 3 new prompt line. Pronipt lines are natoed after their first 
word* The procn^t line you first saw was the "COHMAWD" prompt line. 
This one is the "FILER* prompt line. Sometimes we say that you are "in 
the Filer" when this line jg at the cop of the screen. Each of the 
letters on the prompt line representg a task that you can ask the aystem 
to do- For example, to change the date, press D (again, just type the 
single key, without preesiag RETURM or any other key). 

When you do, another message is put on the screen. It says: 

DATE SET: <l . . 31>-<JAN* ,DEC>-<00. ,99> 
TODAY IS 25-JUL-79 

NEW DATE ? 

It doesn't really mean that today is 2&-JUL-79 (or whatever date your 
screen shows), but that the Apple THINKS that la today's date- Since it 
Isn t, you can change the date Co be correct- The correct form for 
typing the date is shovm on the second line of the message: one or two 
digits giving the day of the month, followed by a minus sign, followed 
by the first three letters of the name of the month, followed by another 
minus sign, followed by the last two digits ol the current year. Then 
press the key marked RETURH , 

If the [uonch and year are correct (as they will often he, when you 

change the date) all you have to do la type the correct day of the 

month, and press the ftETURN key* The system will ajj^ume that you mean 

to keep the same month and year displayed by the message- I£ you type a 

day and a month, the system will assume you m&an to keep only the year 
the same* 

Go ahead and make the date correct. This Is your flrat interaction with 
the system, and Is typical of how the system ±a used. In general, at 



150 Af^E PASCAL LANGUAGE 



m 






1 

3 



the cop of the screen there will usually be a prompt line which 
represents several choices of action. When you type the first letter of 
one of Che choices, either yau will be shown a new prompt. line giving a 
further list of cholceSi or else the system will carry out the desired 
action directly. If you type a letter that dotis not correspond to one 
of the choices, the prompt line blinks but otherwise nothing happens. 
Remember to type only a single letter to Indicate your choice; it Is not 
necessary to press the HETUM key afterward, 

Sometimes, aa when setting the date, you are asked to type a responde of 
several charactere* Vou tell the aystem that your responBe is complete 
by pressing the RETURJl key. If you make a typing error before pressing 

the RETUKM key, you can hack up and correct the error by pressing the 
left-arrow key. You should experiment by making deliberate errors In 
entering a dace, and then erasing the errors with the left-arrow key. 

One further note. Normally, your new date is saved on the diskette, so 
the system "remembers" this date the next time you turn the Apple on. 
Uowever, since you are using the wrlte-protected diskettes chat came 
with your Language System, your new date was not permanently saved. The 
next tine you turn the Apple off, the new date will be "forgotten*'. By 
the end of this sesaion, you. will have made backup copies of the 
Language System diskettes* From then on, you will use these copies, 
which are not wrlte-protected, and your date changes will be saved 
correctly. 

MAKING BACKUP DISKEHE COPIES 



WHY WE MAKE BACKUPS 

Ask yourself this question: What would happen to your system if you were 
CO lose or damage one of the system diskettes (APfLE^;, APFLEl:, 
APPLEZ:, or APPLE3:)? It would he as bad as losing your Apple, as Ear 
as your being able to us>o Pascal* 

These diskettes are quite precious* The first thing you should do, 
therefore, is to make backup copit^a of them. Afterward, you should 
never use the originals, but put them someplace where the temperature is 
moderate, where there ia no danger 'of them getting wet, and where such 
diskette destroyers as dogs, dirtj children, and magnetic Elelds cannot 
get at them* 

A truly cautious person will keep on hand two backup copies of each 
original* That way, you will need to use an original only In the very 
rare case when both of Its backup copies are lost (srfien one copy Is lost 
or damaged, another backup copy Is made from the surviving backup 
copy). If your backups were damaged or erased while In use, find out 
why they were destroyed before inserting your only surviving copy* 
Using diskettes fcr which you have backups, repeat the procedure that 
destroyed the first diskettes; if you can't figure out what the problem 
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Is J Cak« your a/stem tq the deaXer to loake sure it la Vorklag 
correctly* 



HOW WE MAKE BACKUPS 

The Apple Pascal systcia can copy all the laf [3riiLatlan from one: dlskigtCe 
(or any p{?rclon o£ the iafarmaClan) onto another dlsketcS' But the 
sy&CeiD cannot score Inforiciation on a new dlskacte, Just as that diskette 

comes from the computer store. Therefore, the aystem Is supplied wtch a 
program that allows you Co take any 5 -Inch floppy diskeC te and "f ofniac" 
it sa that It wllL work with the Apple Pascal Hystem, 

Incidentally, chia is one of the nl te little things about the Apple 
system" ANY high-quality 5-inch floppy diskette (Apple recommende 
diskettes laflde by Dyean Corporation) will work on it. Some systema 
require you to have "1^ aector" or "13 Bector"or "soft sectored" 
diskettes* The Apple doesn't care, it takes any of these kinds of 
diskettes, and (through the FORMATTER program) makes them into the kind 
of diskette it needs* 

If you have been following this dlgcusslon by carrying out the 
instructions on your Apple, the FILER prompt line should be showing at 

the top of the screen: 

FILER: G» S» N, L, R, C, T, D, Q 
Type Q on the keyboard to quit the Filer , 



GEHING THE BIG PICTURE 

When you Quit the Filer, the disk nfalrra, and you see the COtWAM: prompt 
line again: 

COMiANC: ECEXT, R(IJN, r(ILE. C(OMP. L(1H 

There Is actually more pf this prompt line, off to the right of your TV 

gr iQDnltor. To see the reat of the screen, hold down the key marked 

CTRL and, uiille holding it down, press the A key right alongside It. 
(Or, to be brief, ue say: "press CTRL-A".) 

You now see 

K, X(BCUTE, A(SSEM, D(EBUG,7 

ThlB Is simply the rest of the line that began "COHMAMD;". All 
together, the full prompt line would look like this; 

COMMAND; ECDIT, R(IIN, FCILE, C(OMP, 1(INK, XCECUTE, A(SSEM, D(EBUG,? 
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The Apple Pascal syBtem displays information on a "screen" that Is 60 
ch&raccers wide, buc your TV or monitor shows only the leftoiDSt 40 
character^ or the rlghtmoBt it^ characters at any one tiiae. You Ui^e the 
CTBL-A trick whenever you wish to see if there is more stuff on the 
other ^lialf" of the screen. Repeated pressing of CTRL-A flips back eftd 
forth between the left half of the screen and the right half* Also, 
sometimes the TV display will seam to be blsnk. This might mean that 
you Bre just staring at the empty right half of the screen* Before you 
eome to the conclusion that something ia wrong, always try CTKL-A. Ydu 
get back to the left side of the screen by typing CTRL-A again, and you 
night find chat everything Is OK after all. 

Suismary of chle digression' The screen is really tvlce &b wide «a it 
looka. To flip from the left side to the right side or back again, you 
type CraL-A* 



FORMAHING NEW DISKETTES 

When the COMMAND protupt Hue la showing at Che top of the Jicreeni remove 
your syatem diskette ( AFFLEl: or APPLET: ) from the disk drive and 
place the diskette AI'PLE;3; in Che drive. This has to b-e doue because 
the FOBHAriER pcogran is on AFPLE3: . Nov^ type 

and the screen responds: 

EXECUTE WliAT FILE? 



You type 



APPLE3: FOIWATTER 



and press the RETURN key* The disk whirrs a bit and the screen saya^ 



APPLE DISK FOiiMATTER PROGRAM 
FORMAT WHICH 1>ISK (4p 5, 9..1Z) 



T 



Nov comea a grand session. Take all the new, blank diskettes that you 
are going to use with the Apple Pascal System (but not, of couraet any 
diskettes chat have precious Information on them, such as the diskettes 
that came with the Apple Pascal System) and place them Ici a pile* Their 
labels should be blank. Make sure that you don't have any diskettes 
with data in a non^Pascal format, such as BASIC diskettes: the Apple 
fascal systein will be unable to read them, and will regard thea as 
blank, erasing any old lEionnatlon in Che fonaattlng process. 
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KemovG the diak^Cte A?PLE3: from the disk drive, and plate one of the 

blank diskettes into the drive. Type 



and press the RETURN key* 

If the diskette In Che drive lias already been formatted, yqu will 
receive a warning. For example, If you have left APPLES: In the drive 
you will he warned with the 



DESTRUY DIRECTORY OF AFFLE3 ? 
At this point you can type 

(which stands fpr "No") without pressing the RETURN key, and your 
diskette will not be destroyed* 

Let's assume that you have placed a new, unformatted diskette la Che 
disk drive ■ Then you will not get any warning, but the Apple will place 

this message on the screen: 

NOW FORHATTING DISKETTE IN DRIVE A 

The drive vlll make sooe cllcklDgs and buzziaga and begin to ^Irr and 
zlck* The protess takes about 32 seconds* V?hen formatting Is complete, 
the screen again shows the message 

FGEtMAT WHICH UISR {it, 5» 9,, 12) ? 

Nov you have a foroifiiCted diskette. We suggest that yoa write the ward 
"Pascal*' in s^iDall letters at the top of the diskette's labels using a 
narking pen. Do not use a pencil or ballpoint pen, as the pressure may 
damaee the diskette. The lab^l will let you know that the diskette Is 
formatted for use with the Apple Pascal systein,. and you can distinguish 
it from unformatted diskettes, BASIC diskettes, or diskettes for use 
with other systems. 

While you are at It, repeat this formatting process on all the new 

diskettes that you want to use with the Apple Pascal System* VitU each 
new diskette, place it in the disk drive, type A and press the RETlfRW 
key, 

You may wonder lihy your one-and-only disk drive is called "'A"* There's 

no good reason for thla, it's just that the disk drive was assigned the 

number i- Why, Iti Spanish, is the word for window "ventana"? tt just 

happened that way. 
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When you have finished forinattlng all ycur new diskettes, and have 
written the word "Pascal" on each of them, answer the question 

FORMAT WHICH DISK (4, 5. 9,.U) 7 

with a simple press of the key marked RETlHtN , You get the inessage 

PUT SYSriK DISK IN ff4 AMD PRESS RETURN 

By "SYSTEM DISK" the Apple iieans "APFLEfl:'* (unleas you stopped after 
Step On>e of the startup procedure, and continued to use APFLEl : aa your 
systeiB disk) t By "tfi*" the Apple loeans the disk drive. SDmetimea your 
disk drive is called "DRIVE 4" and sooLetlmes "iCAj", but It's all the 
same thing* 

Do as It saya, place the diskette icarked AFFLE0: In the disk drive (or, 
as we say in Apple Pascal Jargon, "Put AFFLEE9: in ^Ai") and press the 
RETURN key. 

The /^ple says* 

THAT'S ALL FOLKS... 

And If you watch Che top of the screen, the line.' 

COKKAND^ ECDn, atUW, F(ILE, C(OI^* L(INK, X(ECUTE, A{SSEM, DtEBQG,? 

appears <of course. It doesn't all appear; but you know ic's there, and 
can check with CTRL-A) , 



MAKING THE ACTUAL COPIES 

As you have seen, you can get into the Filer by typing F when you have 

the COMMAND prcinpt line on the screen. You must have diskette APPLEIj 

or diskette APPLE0: in the disk drive when you type F for the Filer, or 

(if APPLEP: i3 your system diskette) you will get the message 

NO FILE APPLE0:SYSTEM»FILER 

If this happonR, just put APPLE0: in the disk drive and type F again. 

The Filer Is that portion of the system that allows you to oianlpulate 
Information on diskettes. One of the Filer's abilities is to transfer 
Information from one diskette Co another. To invoke this facility, oace 
you have the FUjER pronqjt line on the acreen, type T for T transfer. 



STARTING (ONE DRIV1E) 155 



I 



This Is vhsL you see: 

TRANSFER ? 

Place diskette APPLET: into the disk drive and answer che quoBClcn as 
follows: 

APPLE3i 

which Deans chat you vant Co tranefer the entire cotitenca of the source 
diskette called APPLE3: - After you have specified which dlsketCe'^B 
Inforioatlon yau want trsnaEerred (and pressed che ke:y marked RETURN ), 
the con^utec checks tQ m^ke sure the correct diskette la In the disk 
drive. If you have forgotten to put diskette APPLE3: In the drlve» 
Chen you will see the EDessag« 

APPLE3 : 

NO SUCH VOL OH-LINE <SOURCE> 

In that case you must type T for Transfer again » and revest the 
process- With the correct source dlekette In the drive, the Transfer 
proceea continues and the con^uter aaka the next obvious question; If 
you are golag to traasfer something, then 

TO WHERE ? 

Answer thia question by typing 

BLANK: 

This iB the naiae of the destination diskette^ onto which you want 
APPLE3:'s information transferred. "BLANKi" Is any of the diakettea 
that you juat f ormact'eid* When a diskette is forioatted It ia 
automatically given the name BLANK: * Incidentally, those colons (:) 
are very impottant* You use them to indicate that you are referring to 
an entire diskette, and not Juat a part of one. 

After you have told the coinputer where you want APPLESi'a Inforinatlon 
tranflferrEd (and preased the key marked RETURM ), it saya: 

TRAMSFER IS? BLOCKS ? (Y/N) 

Thla oessage la mainly therG to give you a chance to abandon the 
transfer If you omde a typing error In the nam&E of the source or the 
destination dlflkettes> The phrase "'ZS0 BLOCKS" coeans merely "THE HHOLE 
DISKETTE". In any case, you type 

T 

The disk whirrs and zlcks a few tinies, and you see the raessage: 

PUT :n BLAI^K: 

TYPE <SPAGE> TO CONTINUE 
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Do as It says- By the coloOt you know that it nteans to put the diskette 
called BLANK: Into the disk drive- The second line tells you to press 
the space bsr when the diskette la In place (and the door closed, of 

course) > 

All the inforpaclon which la on dlak&tte APPLET; » including the 
diskette's naiiis» will be copied onto diskette BLANK;, completely 
overwriting BLANK:* Therefore, the computer warns you that you are 
about to lose any informaclon that might be stored on BLANK.:, It aays 

DESTROY BLANK: ? 

Since you want to turn BLANK: Into a perfect copy of APPLE3:, the answer 
is 



The process Is under way* The computer will tell you to first put in 
one di&kette and Chen the other» Follow the instructions* Your screen 
vlll look like this after a while: 

Pin APPLE3: IW UNIT #A 
TIFE <5PACE> TO CONTINUE 
PirC BLANK: IN UNIT #4 
ryPE <SPACE> TO CONTINUE 
PUT APPLES: IN tJNIT #^ 
TYPE <SPACE> TO CONTINUE 
PUT BLANK: IN UNIT H 
TYPE <SPACE> TO CONTINUE 
PUT AFPLE3; IN UNIT tfA 
TYPE <SPACE> TO CONTINUE 
PUT BLANK: IN UNIT ^4 
XyPE <SPACE? TO CONTINUE 
PUT APPLE3E IN UNIT i?4 
TYPE <SPACE> TO CONTINUE 
PUT BLANK: IN UNIT ^4 
TYPE <SPACE> TO CONTINUE 

and so an> You will have to Insert the two diskettes a total of Z0 
times, and preaa the spacebar 2^ tines, to copy the entire diskette- 
When copying is done, the screen celebrates by saying 



APPLE3: 



— > BLANK; 



by this cryptic remark, the computer ia telling you that the contents of 
APPLE3; , Including the diskette's name, have been copied onto the 
diskette that used to be called BLAKK: * This is just what you wanted. 
Mow, writing lightly with a marking pen (da not use a pencil or & 
ballpoint penl , write "APPLE3:*' on the new diskette's label- It Is very 
in^ortant to label diskettes ItHDedlately, so you know what information 
they contain. 
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DO IT AGAIN, SAM 



Ygu should^ at this Ciroc^ make sure tliaC you have at least one backup 
copy of each of tha Pascal syateni diskeCtee: ATeiE^: , APPLE!:, APPLE2:, 
and APPLE3; * Then you should store the original diskettes away in a 
safe place. 

Wheu you are through making backup copies, be sure to put APPLE0; (or 
APFLEl: it you are uaing that as your system diskette) back into the 
disk drive, BEFORE typing Q to Quit the Filer- If you Eorget to do 
this, the eystem will atop responding cq the keyboard after you type Q 
you will have to turn the Apple off and repeat the entire startup 
procedure. 



USING THE SYSTEM 



A DEMONSTRATION 

Ac last» cihe reward for all your work to this point: you are finally 
ready to use tb& Apple Pascal system to run a program- Diskette APPLE3: 

contains several small "demonstration" programs* To aee a list of those 
prograiiLS, put APPLE:0: in the disk drive and enter the Filer (by typlug F 
In response to the COMMAND prompt line, remember!)* When the FILER 
prompt line appears on the acreen* put AFPLE3: in the drive ai^d type L 
CO List the diskette's directory. The Filer says; 

DIR LiSTlMti OF 7 

In reeponsG. type the name of the diskette whose directory you wish to 
see; 

AFPLE3; 

When you press the RETURN key, a long list of program files appeara on 
the screen^ many of ttiem both In their -TEXT versions {the form In which 
they are written and edited) and fllao In their coinplled .COI>E versions 
(the forni in which they can be executed)* When the screen Is f u II ^ the 
display i^tops and the nessage 

TYPE <SPACE> TO CONTINUE 

appears at the top of the screen. Press the Apple's spacebar to see the 
remaining files. For now, we are Interested in the file named 
GRAFTJO-W-COUE , But betore executing this program, you ruust Transfer It 
CO your system diskette, APPLEIJI: (raoBt graphics progranis inust use 
routines from the '^systam library", a file on APPLE0! and also on 
APPLEU )* In response to the FILER prompt line, type 
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The Filer says 

TRANSFER ? 
Answer the quesclon as follows; 

APPLE3:GRAFUEM0.C0DE 

which means you wane to transfer only the file named CRAFPEMO-COUE froio 
the source diskette named APPLE3: - The Filer checks to see that 
APPLE3; IB in the disk drive» and that It contains a file natned 
GRAFDEMO.CODEp and Chen asks 

TO WBERE 7 

Vou know chat you want a copy of the file GRAFDEMO.CODE transferred to 
the destination diskette APPLE0: * To avoid ronfusion, let's give this 
copied file the same name when it is trsneferired to APPLE^: . To do 
this, answer the question by typing 

APPLE0 jGllArDEMO .CODE 

Note: you MUST specify a name for the file on Che de&Clnatlon diskette- 
1£ you forget to type a file naiae, the Flier Chinks you are referring to 
the etiClre diskette, and asks 

DESTROY APFLE0; ? 

Since you do not wish to destroy APPLET: , type 



Wowp if you have typed all of your responses correctly, a new display 
appears: 

PUT IN AFPLEiJ; 

TYPE <SPACE> TO CONTINUE 

Follow the directions, putting APPLEfl: in the disk drive and pressing 
Che Apple's spacebar- You are soon rewarded with the inesaage 

APPLE 3 ! GRAFD EMO * COD E 
---S APPLE0:GRAFDEMO-CODE 

Thla telle yau that a copy of Che file GRAFDEMO-CODE on dlskecce AFFLE3; 
has been auccesefully transferred to a file tmmed GRAFDEMOtCODE on 
diskette Ai?PL.E!3i ^ Since the syatem diakette APPLE0: is already in the 
disk drive, yau may now safely type Q to Quit the Filer, when the 
GOMHAHD prompt line appears^ type X for XCecute- The Apple a^ys 

EXECUTE WHAT FILE? 
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Ansver by typing the name □£ the file you Just transferred to AFFLE0; 

APPLES! :GRAFDEMO 

Nott: DO NOT type the suffix .CODE ; the system knows ^ou can ejcecut^ 
oul^ B code file, so IL autooiatlcaliy supplies the suffix ■CODE for ypu, 
In addition to any namie that you type- 

When this message appears: 

PRESS ANY KEY TXJ iJUIT- 

PLEASE WAIT WMILEi CREATING BUTTERFLY 



Just 



the program Ig running- After a short pause, the display beglnSi 
flit back and enjoy It: soon you'll be writing your own programs 
yourself' When you are tired of watching, press the spacebar on the 
Apple's keyboard to return to the COtJMAND prompt line. You can use thlt 
same procedure to run any of the programs on AFFLE3: > These pTOgranis 
and their purposes are described in the Appendl?: A. 



DO IT YOURSELF 

Now, for some nore experience at UElng the Apple Pascal system, let's 
try writing a Little program. This discussion will aaaume that you are 
using your nev copy of APPLE0: as your system diskette (or "boot 
diskette*' es it is often called). Thle copy is not wrlte-protected and 

you have never used the Editor to create any new files on it before 
(It's all right If you have added the file GRAFDEMO.CODE to ic). 

With the COMMAND protnpt line shoving, and with APPLE0; In the disk 
drive, type E to select the E(dic option-^ Soon, thja loefisage appears: 

>EOIT: 

NO WDUKFILE IS PRESENT. FILE? ( <RET> FOR NO FILE <ESC-RET> TO EXIT ) 



Aa usual, you atust use CTKL*A to see the right half of the cKssage- 
This a>sssage gives you some Inf ormatlon and some choices. The first 
word, :>t:l>lT: , tella you that you are now in the Editnr. The next 
eentence, NO WQRKFlLE IS FftESEST , tella you that you have not yet used 
the Editor to create a "worltfile'\ which Is a "scratchpad" diskette copy 
of a program you aro working on* If there had been a workf ile on 
APPLE0I , that file would have been read into the Editor automatically* 

Since there was no workfile to read In^ the Editor asks you, FILE? If 
you now typed the name of a .TEXT file stored on APPLE^Ij, that textflle 
would be read Into the Editor. However » there are no .TEXT fllea on 
AFPLE0; yet, and begides, you want to vrlce a new progtam. In 
parentheses, you are shown how Co ssy that you don't want to read in an 
old file: <RET> FOR NO FILE . This means that* If you press the Apple's 
RETURN key* no file will be read In and you can start a new file of your 
own. That's just what you want to do, ao press Che Apple's RETURK key 
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(the rest of the aie?sage saye if you first press the ESC key and THEK 
pre^fl the RETURN key, you'll be sent bsck to the COMMAt^ proinpt line). 
When you have pressed only the ELETURN key, the full EDIT prompt line 
appears: 

>EDlTt A(DJST CCPT D<LErE FflND KNSRT J(MP R(PLACE QCUIT X(CHHG ZtAP 

The chapter called THE EDITOR in the Apple Pascal Operating System 
Manual esplalns all of thciaq connnand options in detail; for now you will 
only need a few of them» The first one yau will us« Is 1(NSR1: , which 
selects the Editor's mode for inserting new text. Type I to select 

In-sert mode, ^.tid this prompt line appears: 

>1NSERT: TEXT |<BS> A CHAS,<DEL> A LINE] [<ETX> ACCEPTS, <ESC> ESCAPES) 

As long as this line is showing at the top of the screerij anything you 
type will be placed on the screen, just to the left of the white square 
"cursor"* If the cursor is in the middle of a line, the rest of the 
line Is pushed over to niake room for the new text. If you make a 
mistake. Just use the left-arrow key to b^ck^pace over the error, and 
then retype* At any tine during an insertion. If you press the Apple's 
ESC key your insertion will be erased. At any tioe during an insertion. 
If you press CTRL-C the insertion will be made a permanent part of your 
file, safe from being erased hy ESC or by the left-arrow key* You can 
then type I to reenter Insert mode and type more text* 

Nov for our program, With the IS^SERT prompt line showing, press the 
RETURN key a couple of tioieBp to move the cursor dcwuj and then type 

PRORAFM DEMOj 

You can use any name for your program, but in this discussion it will be 
called DEHO . Now press CFRL-C (type C while holding down the CTRL 
key). Your insertion so far is inade "permanent", and the EDIT pronqjt 
line reappears. But, horrors! You made several typing errors when 
typing the word PROGRAH - Since you have already pressed CTRL-C , it la 
coo late to backspace over your errors and retype them. 

Fortunately, there are other ways* First, let's correct the missing G 
in PROGRAM - Using the left arrow key, move the cureor left until It is 
Bitting directly on the R * Then type I to reenter Insert mode- Ignore 
the fact that the remainder of the line seems to have suddenly 
diseppeared, and type the mlaslng letter G . When you press CTRL-C to 
nake this Insertion permanent, the rest of the line returns; 

FROGRAF^! DEMO; 

The letter F is certainly not needed, so move the cursor right (using 
the right-arrow key) until It Is sitting directly on the F . Wow type D 
to select Che Editor's fl<LETE option. When the DELETE prompt line 
appears, press the right-arrow key once* The offending F instantly 
disappears. What happens next is similar to Insert mode; if you press 
the ESC key, the deletion Is forgotten, as If it bad never happened- If 
you press CTRL^c , the deletion is made a permanent part of your 
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The line claace la 



file. To remove that F permanently, press CTRL-C 
to fill the deleted letter's plate; 

PROGRAM DEMO; 

Now you know how to use Che Editor's Insert and Delete modes to write 
text and to torrect your errors. Try typing the rest of program DEMO 
Into your file* He sure to "accept" your InserclonSj from time to time, 
by pressing CTHL-C . That wfiy, you minimize your loss if you 
accidentally preas the ESC key. Here Is the complete program; 

PROGRAM DEMO; 

USES TURTLEGRAPHICS, APPLESTUFF; 
VAK ANCLE^ DIST/tNCE : INTEGER; 

PROCEDURE CRAWL; 

BEGIN 

MOVE U * DISTAKCE); 

TURN (AMGLE) 
END; 

BEGm 

ANGLE :=» fl; 
REPEAT 

INITTURTiE; 

PEMCOLOR (WHITE); 

FUR DISTANCE ;- 1 TO 99 DO CRAWL; 

Al^GLE :- ANGLE + 5 
UNTIL b^YPRESSj 
TEXTMODE 
END. 

When you are typing this profiran, the ptinctuatlon and spelling naiBt be 
exactly as shown* The indentation of the lines Is not Important, but It 
easier to read as shown. You will notice that, once you have started a 
new Indentation, the Editor nmlntalud that indentation for you. Tq move 
back to the left* just pre^ss the left-arrow key before you type anything 
oti the nev line. 

Program DEMO makes use of graphics routines In the Unit TURTLEGHAPKICS , 
and uses the keypress function from the Unit APPLESTUFF (see Chapter 7 
for more details). The third line of the progran declares two Integer 
variables, DISTANCE and ANGLE. Next , a Pascal procedure naraed CRAWL la 
defined, between the first BECXN and END; < From here onj each time 
this new Pascal statement CKAWL is used, a graphics "turtle" will trace 
a line on the screen^ of length 2*DXSTANCE movlnfi In the current 
direction, and will then change the direction by an amounc ANGLE* 

The next BEGIN and the last ENJD. outline the raaln proEram. The portion 
of the program from REPEAT to UNTIL KEYPRESS is repeated over and crver 
again,, until any key on the Apple's keyboard la pressed* 
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In each repetition, the screen is cleared and the tracing color is set 
to WHITE. Then the procedure CRAWL is performed, first with the value 
of DISTANCE set to one, theti with DISTANCE Eet to the value two, and so 
on, until DISTANCE Is set to ^9 * The "turtle" moves, then turns, then 
moves some more, then turns again, and so on, for 99 steps- That 
completes one design on the screen. In the next repetltlonj if no key 
has been pressed, the ANGLE ha.3 increased by 5 degrees, the screen is 
cleared by IHITTURTLE, and the whole process starts again. 

Wow you should save this prograni+ With the EKIT prompt line showing, 
type Q to select the QfUIT Dptiori' the following [o&SBage appears: 

>qUIT; 

UCFDATE THE UOfcKFILE AMD LEAVE 
eCXlT WITHOUT UPDATIfJ& 

R{ETURN TO THE EDITOR WITHOUT UPDATING 
W<RITE lU A FILE NAME AND RETURN 

Type U Co create a ^"workfile" diskette copy of your proBram (future 
versions of this file will be "Updates"). This worfcflle la a file on 

your boot diskette called SYSTEM. WRK> TEXT * The Apple says 

WRITING... 

YOUR FILE IS 33? BYTES LONG, 

(the Qumber o£ "byisB may be a little different) and then the COMMAND 
prompt line reappears. Now type R. to select the R(U3^ option. This 
autotnatlcally calls the Compiler for you, since the wockflle containa 
text. If you have typed the program perfectly, the following niesiaages 
(agalo, perhaps with slightly different numbers) appear, one by one: 

COMPILING..* 



PASCAL COMPILER II . 1 (B2BI 

< 0>. . . . 

TURTLEGR [ 2-^83 WORDS] 

< 5> 

APPLESTU I 16(78 WORDSJ 

< 3«> 

CRAWL I 1098 WORDS] 

< A6> 

DEMO [ 11^9 WORDS] 

< 51? ** 

3g LIKES 

SMALLEST AVAILABLE SPACE - 1098 WORDS 

If the Compiler discovers mlstakeQ, it will give you & message such as 

PROFRAM «« 

LINE 2, ERROR 18: <SP> (CONTIMUE) , <ESC> {TERMINATE ) , E{DIT 

Don't despair; just type E for E(DIT . Your workflle will be 
automatically read back into the Editor for repairs* Read the error 
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message at the top of the acreea, prees the spacebar, and make any 
necessary changes using Knsert and D(elete. Then Q(ult, IKpdate the 
workfile, and R(un your program again, by typing (J U R (the Apple will 
«tore up several conDDands In advance)! 

When your program has been successfully CaToplled » It is autoniatlcally 
executed^ You vlli see the message 

HONNING . . . 



The workllle on APPLE0: now contains the text version of your program In 
a. file named SYSTEM. WRK- TEXT » and the compiled P-code veralon of your 
prograiii In another file naiaed SYSTEM* WRK* CODE , When your prDgracu is 
running as you want It to, you should save the text and code vorkfile 
under other filenames. With the COMMAND prorapt line she<wlng^ type F to 
enter the Filer. When the FILER proDi^C llae appears^ type S for S(ave. 
You will be asked 

SAVE AS ? 

and you should respond by Cyplng any filensme vlch fewer than 10 
charactera* For exsnpiei you might type 

DEHO 

This changes the names of the workflle from S Y STEM* WRK, TEXT to DEMO, TEXT 
, and from SYSTEM. WRK. CODE to DEMO. CODE , If you want to keep a 
pertnanent copy af your program on another diskette, you should now use 
the T transfer conHTiand to transfer DEMO, TEXT and PEMO«CODEi one at a 
tlQien to the other diskette, Remember to wait for the prompt message 
before removing the source diskette from the drive and putting in the 
destination diskette. 



WHAT TO LEAVE IN THE DRIVE 



fe 



and then a horizontal line appears on the screen. That Is the first 

design your program draws; the white "turtle" mves out a distance 2*1 , li 

turns an angle ^ ; moves 2*2 , turna ; movea 2*3 , turns ; etc. 

Keep watching as successive designs turn through larger and larger ^ 

angles between moves. When you want to Interrupt the program, press any C 

key on the keyboard. 

Try loaking changes to the prograiQ, by setting a different starting 

ANGLE, or a different Increment to the ANGLE, or a different distance ta ^ 

MOVE. To da Chia, type E for EfDIT^ use 1(NSRT and D<LETE to make E 

changes, and then Q(ult, HCpdate Che workflle* and Rfun again by typing 

q U R . This cycle of Edlt-Run-Edit-Run is the basis of all program ^ 

development in the Apple Pascal system. 



E 
if 



When you turn the Apple off. It is a good ide^ to loave the diskGtte K 

called Ai'PLEl: In Che disk drive* If some other diskette or no diskette 

is in the drive when the Apple is turned on ^ the drive vill spin __ 
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Indefinitely" If this continues for hours axid hours, some wear will 
take place on the drive end any diskette In it. So, It is a good idea 
to make a habit of leaving a copy of APPLE 1: (now that you have copies } 
in the disk drive trfien ycu turn the system off, f APPLET: will not do, 
as it is tfllBslttg a file that is needed for the first stage of ayatem 
startup* ) 

Of course, if you turn on the system and APPLEl: is not In the drive. 
Just presfi the key tnarked RESET . Place APPLEl: In the drive and turn 
the system off and then on again* No damage results from turning on the 
Apple with the wrong diskette (or no diskette) in the drive- Gradual, 
unnecessary wear results from leaving the disk drive running for a long 
period of time with the incorrect diskette (or no diskette) In the 
driven 
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STARTING UP THE SYSTEM 



To start the syatem» place diskette APPLEl: in the disk drive; then tarn 
on the Apple's power* When the "WELCO^tE" message appears, Pascal is 
running, Uaing AJ'FLEl: as the system diskette, you can file, edit, and 
execute previously compiled programs! but you cannot compile new 
programs* To change system diskettes , place AfPLE{9i In the drive; then 
press the Apple's HJISEX key* Again, when the 'VELCOME" meeHage appears, 
Pascal la running. Using APPLEi?: as the system diskette, you can file, 
edit, compile, and execute pTograms; but you cannot start up the syateHi 
from pgwer-on. 



FORMAHING NEW DISKEHES 

To forioat d diskette, have Pascal's COMMAND prompt line showing- 
Place diskette APPLE3: In the disk drive, and type 

X 
In response to the query: 

EXECUTE WHAT FILE? 
type 

AFPLE3:F0RMArTER 
When the question; 

FORMAT WHICH DISK ? 
appeara, place the new diskette in the disk drive, then type 

and press the RETURN key. The diskette will be formatted. To leave 
the fortnattlng program, press the RETURN key in response to the WHICH 
DISK question, A nevly foruiatted diskette has the name BLAKKi 
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COPYING DISKEHES 



t. 



To copy a dlske^cie^ have the COMMAND proinpt line showing, and put 
dlaketce APFLK0: or APPLEl: in else disli drive- Get Into the Filer 
by typing 

F 
When the FILER protopt line appears, put Into the disk drive the source 
diskette Co be copied* Then type 

T 
To the question: 

TRANSFER ? 
reply by typing the naoie o£ the source dlak^tte to be copied, and then 
pteaa the FiETURK key< For example; 

APFLE3: 
To the Dext quescion : 

TO WHERE 7 
reply with the name of the destination diskette that Is CD become the 
backup copy. For exanple: 

BLANK; 
Then follow the Inatructions displayed on the screen, switching the 
diskettes back and forth until the copy la complete* Before you Quit 
the Filer, he sure to put your system diskette (usually APPLE^;) back 
in the drive. 

Note: you cannot make a copy onto a destination diskette that haa the 
sam& riame as the source diskecte- Use the Filer to C(hBnge the name 
of either diskette, at least while making the copy. 



EXECUTING A PROGRAM 



To execute a prevlouBly compiled program, put your system diskette 

(APPlEj): or APPLEl:) Into the disk drive* With the COMMAND procipt 
line showing, enter the Filer by typing 

F 
When the FILER pronspt line fippears, put into the disk drive the 
diskette containing the program codeflle that you wish to execute- 
Then type 

T 
for T(ransfer. To the question 

TRAITS FER ? 
reply by typing the natne of tlie program's diskette and codeflle. For 
eKamplt^ , 

APPLE3 ; GRAFliE^O , CODH 
To the next question 

TO WHERE ? 
reply with the name of your system diskette, and the sane filename (or 
another name, if yon wlsh)> For examplet 

APPLEfl ; URAFD EMO . COD E 
When you are prot^ted 

PUT IN APPLET: 
follow the Instructions, and press the spacehar- The program Is then 
transferred onto your system diskette, which is where it cnust he lo 
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order to execute it* Now type q to q(uit the Filer, and Mhen the 
caMMAflO prompt appeara , type X for XCecute- When the Apple prompts 

EXECUTE WHAT FILE? 
answer by typing the name of your system diskette and the newly 
transferred codeflle you wlah to have executed. DO HOT type the -CODS 
suffix- In this example, you would type 

APPL£0:GRAFI:EMO 
The program should now run. 



WRITING A PROGRAM 



iskette (which 



to start a new file in the Editor, put your aystem 
taust be APPLE0; if you want to K(un your program) Into the disk 
drive. With the GOflKAND protii|)t line showing, type F to enter the 
Filer* Then type N for Ktew* If you are asked 

THROW AWAY CUEtRENI WOKKFU^E 1 
type Y for Y(eB- When you see the message 

WORKFILE CLEARED 
type Q to q(uit the Filer, and then type E to enter the Editor. 

This message appeacs ; 

WO WORKFILE IS PRESENT- FILE? < <RET> FOR NO FILE <ESC-ELET> TD EXIT ) 
Press the RETURN key, and the full EDIT: prompt Une appears- Yon can 
now insert Ce?ct at the cursor position by typing I for I(nserc and 
then typing your program^ Conclude each insertion by pressing CTRL-C 
Ueiete text at the curaot position by cypiuB P for DCeUte and then 
moving the cursor to erase text. Conclude each deletion by pressing 
GTRL-C . When you have written a version of your pxograni, type Q to 
y(ult the Editor, and then typ*? U to U(pdate the workflle to contain 
your Ifitest program version. 

With the COMMAND prompt line showing, you can then type R to R(un 
your program- This automatically ccmplles the text workfile (using 
the Coii5]iler program on APPLEUOi stores the coinpiled code workflle, 
and executes It. To reenter the Editor, type E la response to the 
COMMAi^U promp:. The text workfile Is automatically read back Into the 
computer. 

When a version of your program la cotaplete, yotj can U£pdate the text 
workflle to contain Chat latest version and It(un the ptDgrain to create 
a code workfilc of that version. To save the workflle versions of 
your program on another diskette for later use, first save the 
workflle under another name on your system disRettc (AFFLE0:)* Type 
r in response to the COHMAMD prompt to enter the Filer, Then type S 
for S(ave. When you see the prompt 

SAVE AS ? 
type the name of your system diskette and the filename under which you 
want your program saved- Do not type any »TEKT or -CODE suffix- For 
exatDple, if you want your program saved under the filename OEHO , you 
might type 

APPL£iS;IlEtK> 
The text workflle SYSTEM* WRK- TEXT la saved as DEMO-TEXT on APPLEfl;, 
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and the code workflle SYSTRM.tflUt.CODE la saved as DEMO. CODE . 

Now you can T(ranBfer Chose files to any oCher dlflkettG^ for safe 
keeping. Type 

T 
and when Che Filer asks 

TRANSFER T 
give the name of qne of Che S(aved files on your system dJsketto. In 
Che previous exatn^slep yau could type APPLEljSiOEMO.TEKT To the next 
question TU WHERE ? fepljr by typing the name of the diskette and file 
where you wish your program file to be scored* For example, you 
might cype MYDISK:DEtlO,TKXT Hie Apple will prompC you when It Is tlrae 
to put the destination diskecce In the drive. When Che text version 
of your pragraci has been transferred onto the destination diskette, 
put your system diskette back in Che drive, Now^ type T for 
T(rans£er again, and transfer the code version of your program Co Che 
destinaclod diskette in Che eame way you transferred the text 
version- 

Remember to put APPLE0: back in the disk drive before CJ(uittlng the 
Filer. 



SS 
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This appendix ia a. tutorial eesslon to get you fltarted using the 
Language Syaceca with Pascal, on an Apple II with two or njore diskette 
drives. If your system haa only one diskette drive, pleaae go back and 
read Appendix D tnatead* 

EQUIPMENT YOU WILL NEED 



You should have the following: 

1. Your itSK Apple computer, vlth a Language Card installod, and at 
least two disk drives. The first two ahould be attached ta a disk 
controller card In slot 6. All yotir dlak controller cards should have 
the new PROMe, P5A and P&A, that carae with tJie Language Syatem. 

2. A TV get or i^dcD rfonltor, connected to your Apple- 

3. The following Laneuage Syetera dlakettear 



a* 


APPLE 1: 


b. 


A1*PLE2 : 


c * 


APPLES: 


d. 


A blarik diskette 


e* 


A second blank dlakecce 



The diskette marked "APPLEl:" Is needed to start che system. The 
diskette mrked '^APPLE2:" adds certain extra features to the ayeteni (the 
Corapller, the AsfieTtibler, and Che Linker)* You will not need the 
diskette marked "APPLET:" until later. The diskette marked "APPLE3:" 
contains a number ot useful utility progrania* A diskette marked 
"iVPPLEia:" Is alBO Included with the Language System, This diskette Is 
nortsinlly used with single-drive Bystems- 

The ApplQ and the TV or monitor should be plugged in* Turn on the TV 
now, so that It can warm up; hut leave the Apple tum«d off* 



MORE THAN TWO DISK DRIVES 



If your aysten haa more than two disk drjvee, the third drive gets 
connected to the "DRIVE V pins on the second controller, which goes In 
slot 5, A fourth drive is connected to the "0RIVE 2" pins On the second 
controller, in slot 5. A fifth and even a aixth drive can be connected 
to a controller in slot A, using the "DRIVE I" and "DRIVE 2" pins, 
respectively- 
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NUMBERING THE DISK DRIVES 



Pascal assigTia a "Volume" numhcr to each of the disk drives. It Is not 
a had idea to place tags with these numbers on your disk drivea* Here's 
how the volume numhers are assigned to the various disk drives: 



APPLE 
DISK DHIVE 




PASCAL 
VOLUME 


Slot 6, Drive 
Slot 6, Brlve 


1 
2 




Slot 5, Drive 
Slot 5, Drive 


1 
2 


#11: 
#12; 


Slot 4, Drive 
Slot A, Drive 


1 
2 


#9: 



You will find that you can refer to any diskette by either the naoie of 
the diskette (e.g., APPLE3:) or by the volume number of the drive In 
which It sits (e.g., i?ll;) 



FASCAL IN SECONDS 



Flace the diskette marked "APPLEli" in disk drive #4: (slot 6, drive 
1)* If you are not familiar with handling diskettes, see the Tnanuals 
that came with your disk drives. Diskettes must be treated correctly if 
they are to last. 

Close the door to djjgk drive i?4; , and turn on the Apple- The rest Is 
automatlct First, the message 

APPLE tl 

appears at the top of your TV or TiionJtor screen, sad disk drive I^Ui'a 
"IK USE" light eomea on. The disk drive eralts a whirring* ^lokklng 
sound that Is as pleasant as a cat's purring, since It lets you know 
that everything is working. The screen lights up for an instanc: with a 
display of black at-signs ( (I ) on a white backj^round, then goes black 
again* Next the other dlak drives are turned on, one at a time, as 
Apple Pascal finds out what Is in each drive. A drive with no dlskecce 
In It may hvzz and clatter a bit. When Apple Pascal cannot read 
anything from a dlak drive, it cecalihrat^s the drive's read-head 
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position (buzz, clatter) aad then tries again. Now disk drive tf4: gtops 
entirely for & nctBent; then it whirrs some more. Finally, the meaaage 

WELCOME APPLE 1, TO 
U.CS.D* PASCAL SVSTEM 11,1 
CURRENT DATE IS 26-Jin.-79 

appears (the date will he dilfErent), followed In a second or ao by a 
line at the tap of the screea: 

COMMANDi E(DIT, R<UN, F(ILE, C(OMP, L(rN 

This line at the top of the ecreen Is called a "prompt line". When you 

see this prompt line, you knov that your Apple conqjuter is mmilng the 
Apple Pascal system. '^ 

Starting the Gystem depends only on having APPtjEl: In disk drive ^4:. 
This time, you left the ether drives emptyj but yon wlU soon discover 
that the syatein etarta more quickly and quietly If the other drives have 
l^?l\ diskettes In then. For now, you could put dlflkettes APPLE2; and 
AffLhJ: in any empty disk drives. Later, you will have other diskettes 
to put in them. In any case, iiake aure you never put Ewo diskettes with 
the same name Into the aystem at the eaine time* This may cauae the 
directories of those diskettes to get scrambled* 



CHANGING THE DATE 

The date that cotnes on the diskette will not be correct. It Is a good 
habit to reset the date the first time you use the Pascal System on any 
given day. It only takes a few seconds. Preaa F en the keyboard 
(without pressing the RETURN key or any other keys). The screen goes 
black, and then this line appears at the top: 



FILER; G. S, n, U R, C, T, D, q 

This Is a new protnpt line. Pran^t lines are natned after their flrat 
word. The prompt line you first saw was the "COMMAHtJ" prompt line. 
This one la the "FILER" prompt line. Sonietlniee we say that you are "In 
the Filer" when this line is at the top of the screen* Each of the 
letters on the pron^t line represents a taak that you can ask the Apple 
to do* For example, to change the date, press D (again, just type the 
single key, without preasing RETURN or any other keys). 

When you do. another message la put on the screen, tt says: 



DATE SET; <1..31>-<JAN,,D£C>-<C 
TODAY IS 2&-JUi-79 

NEW DATE ? 



J.,99> 






i: ! !^ 

E : 3 

E I m 

E 3 

E I 3 

E B| 

E , =^ 



typing the date la shown on the setond Une o£ the mesBage; one or two 
dlKlCe giving the day of the niDiith, followed by a mlnue sign, folloved 
by the first three letters of the name of the month, followed by another 
mlnuB sign, followed by the last two digits of the current year* Then 
ptees the key marked RETURN . 

If the month and yeiar are correct (as they will often he, when you 
change the date) all yoii have to do la type the correct day of the 
month, and press the RETURJtf key. The gystem will assume that you tnean 
to keep the same month and year displayed by the message. If you type a 
day and a iicnth, the Bystem will assume you mean to keep only the year 
the same- 
Go ahead and mke the date correct* This la your first Interaction with 
the system, and ia typical of how the system Is used. In general, at 
the top of the screen there will usually be a prompt line vhlch 
represents aeveral choices of action. When you type the first letter of 
one of the choices, either you will be showti a new prompt line giving & 
further list of choices, ox else the system will carry out the desired 
action directly. If you type a letter that does not correspond to one 
of the choicest the prompt line blinks but otherwise nothing Ixappens. 
fleniember to type only a single letter to indicate your choice; it la not 
neceaaary to press the RETURN key afterwards 

Sometimes, aa when setting the date, you are asked to type a response of 
several characters* You tell the system that your response la complete 
hy pressing the RETURN key* If you make a typing error before pressing 
the RETURN key, you can back up and correct the error by pressing the 
left-arrow key. You should experiment by making deliberate errors in 
entering a date, and then erasing the errors with the left-arrow key* 

One further note. Normally, your new date Is saved on diskette APFLEl:, 
90 the aystsin "remembers" this date the next time you turn the Apple 
on* However, since you are using the urlte-protected diskettes that 
came with your Language System, your new date was not permanently 
saved* The next time you turn the Apple off, the new date will be 
"forgotten". By the end of this session, you will have made backup 
copies of the Language System diskettes. Froiti then on, you will use 
these copies , which are not wrl te "pro tec ted, and your date changes will 
be aaved* 



MAKING BACKUP DISKEHE COPIES 



It doesn't really mean that today is 26-JUL-79 (or whatever date your K gl 

screen shows), but that the Apple THINKS that Is today's date. Since it ^ 

Isn t, you can change the date to be correct, The correct forn for *-- 

E ^ 



WHY WE MAKE BACKUPS 

Ask yourself thla queetion: What would happen to your system if you were 
to lose or damage one of the system diskettes (APPLEli, APFLE2:, or 
APPLt3;)? It would be as had as losing your Apple itself, as far as 
your being able to use Apple Pascal* 
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These dlakettea are quite pretlotia. The first thing you should do, 
Cherefore, is to make backup copies of chem. AfCefward^ you should 
never use che originals^ but put then: someplace where the CGmperature la 
moderate, where there Is no danger of them getting wet, and latiere such 
diskette destroyers aa dogs, dirt* children, and magnetic fields canaot 
get at them. 

A truly cautious peraoTi, will keep on hand two backup copies of each 
orlglaal* That way, you will tieed to uBe an original only in the very 
rare case when both of its backup copies are lost (when one copy la lost 
or damaged, another backup copy Is made from the surviving backup 
tapy). If your backups were damaged or eraaed while In use, find out 
why they were destroyed before Inserting your only surviving topy. 
Using diskettes for which you have backups, repeat the procedure that 
deatroyed the first diskettes, and If you can^t figure out what the 
problem Is, bring your system to the dealer to make sure it Is working 
cocrectly. 



HOW WE MAKE BACKUPS 

The Pascal syatem can copy all the Itiformation from one diskette (or any 
portion of the Information) onto another diskette. But the ayatem 
cannot store inforraation on a new dlakette, just as that diskette cornea 
from the congjuter store. Therefore, the system Is supplied with a 
pcograiE that allows you to take any S-lnch floppy diskette and "format" 
it so that It Vlll work irith the Apple Pascal system. 

Incidentally, this is one of the nice little things about the Apple 
systems AMY high-quality S-^lnch floppy diskette (Apple reccnnmends 
diskettes made by Dysan C^orporatlon) will work on It. Some aystems 
require you to have "10 sector^' or "15 sector" or "aoft sectored" 
diskettes. The Apple doesn't tiare, it takes any of these klnda of 
dlskeccea, and (through the FORMATTER program) makes them Into the kind 
of diskette J t needs. 

If you have been foliawipg this session by carrying out the instructions 
on your Apple, the FILER prompt line abonid he showing at the Cop of the 
screen: 



P. ^ 

K j ^ 

■ j !§ 

m j ^ 
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■ j ^ 
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FILER: G, S, N, L, R, C, T, U, Q 
Type (J on the keyboard to Quit the Filer* 



V 4 
GEniNG THE BIG PICTURE ^ ^ 

When you i^uiit the Tiler, disk drive &U: whirrs^ and you see Che COHMAM) H 3 



There Is actually more of this prompt Une, off to the right of your TV 
or monitor. To see the rest of the acreen» hold down the key rnairked 
CTRL and, while holding it, press the "A" right alongside it. (Or, to 
be brief, we say: "press CTEL-A".) 

Vou now see 

K, XtECUTE, A(SSEM, D(EBUG,? 

TblB Is ainiply the rest of the line that began "COMMAND:", All 
together, the full pronipt line would look like this; 

COMMAND! E(DIT, R(UN, F(TLE, C(Oe^, L(IHK, X(ECUTE, A(SSEM, DfEBUG,? 

The Apple Pascal system displays information on a "screen" Chat is 80 
characteirs wide, but your TV or monitor shows only Che leftmoat 40 
characters or the rightmost 40 characters at any one time* You use the 
CTdL-A trick whenever you wish to eee if there is more stuff an the 
other "half" of the screen. Repeated pressing of CTEtL-A flips back and 
forth between the left half of the screen and the right half* 

Also, sometimes the TV display will seem to be blank. This might tnean 
chat you are just etarlug at the empty right half of Che screen- Before 
you cope to the conclusion that aomechlng Is wrong, always try CTRL-A* 
Vou get back to the left side of the screen by typing CTHL^A again, and 
you might find that everything la OK after all- 

Summary of this diversion: The screen Is really twice as wide as it 
looks. To flip from the left side to the right side or back again, you 

type CTRL-A. 



proinpt line again: 

GOHMAWDJ E(DIT, RCUM, F<ILE» C(OMP, L(tN 



FORMATTING NEW DISKEHES 

Place diskette APPLE3: In any available disk drive except drive #i; - 
This has to be done because the FOKMATTER program Is on AFPLE3:* Now 
with the COMMAND prompt line at the top of the screen, type 



and the Screen re S p otid 9 1 

EXECUTE MEAT FILE? 

You type 

APPLE3iF0R>IATTER 

and press che key marked RETUEU:) 
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The disk drive coataialng APFLESi whirrs a bit and the screen says: 

APPLE DISK FORMATTER PROCEIAM 
FORMAT WHICH DISK <4, 5, 9-.12) ? 

Take all the new^ blank diskettes that you are going to uat with the 
Pascal System (but not, of coursep any diskettes that have precious 
inforniatian on them, auch as the diskettes that came with Che Pascal 
System) and place them In a pile. Their labels should be blank. Make 
Bure that you don't liave any diskettes vith data In a non-Paacal format, 
9uch as BASIC dlakettea: the Pascal system will be unable to read then," 
aad will regard them as blank, erasing any old information In the 
f ormattlitg piToceas* 

ftenove the dlakette In disk drive ff5: <U yours Is a two-drive syetem, 
you will be removing diskette APPLE3; > and put one of the new, blank 
diskettes Into that drive* Then type 



and press the key marked RETURH * 

If the diskette In drive #5; has already been forioatted, you will 
receive a wamins- Foe example, If you have left APPLE3: In that dr:(ve 
you will be warned with the rqessage 

DESTROY DIRECTORY OF APPLE3 7 

At this point you can type 
N 



R j 59 



ir p!^ 
■r '~^ 



(which stands for "No*') without pressing the RETURN key, and your 
diskette will not be deatroyed- Let's afsune that you have s new, b 

unformatted diskette* Then you will not get any warning, hut the Apple 
will place this message on the screen: 



IT" i^ 



P- -3 



NOW FOftHATTlNt; DISKETTE IN DRIVE 5 

Diek drive ifS: will make some cllckings and buzzlngs and begin to vhlrr 
and zick. The process takes about 32 second^' When lormatting la 
coiDplete, the screen again showe the message 

PORHAT WHICH DISK f4, 5, 9*. 121 ? 

Now you have a fortaatted diskette. We suggest that you write "Pascal" 
in small letters at the top of the diskette's label, using a inarklng 
pen. Dd not use a pencil or ballpoint pen, aa the pressure of writing 
may damage the diskette. The label will let you know that the diskette 
1b foriaatted for use with the Apple Pascal system^ and you can 
distinguish It from unforniatted diskettes, BASIC diskettes^ or diskettes 
for 1UH6 with other systems. 
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While you are at It, repeat this formatting process on all the new 
diskettes that you want to use with the Apple Pascal System- With each 
new diskette* place it in drive B; , type 5 end press the SETUHN 
key. 



U 



Notet If you have more than two drives, you Cfin simplify the procedure 

by putting the next diskette to be formatted into any unoccupied drive* 

Then, when the system asks 

FORMAT WHICH DISK (4, 5. 9.-12) ? 

juat type the correct volume number of the drive containing your new, 
blank diskette, and then press the RETURW key, ThlE will save you soine 
dl skecte-swapplng ■ 

When you have flnlahed formatting all your new diskettes » and have 
written the word "Pascal" on each of then, answer the question 

FORMAT WHICH DISK (4, 5, 9**12) 7 
with & einiple press of the key narked RETCRN . You get the message 

THAT'S ALL FOLKS... 

And if you tfatch the tap of the screen, the line 

COMKWJD: E<DIT, RCITN, F(ILE, C(OMP, L(INIC, X(ECirrE, A(SSEMt D{EBUG,7 

appears (of course, It doesn't all appear; but you knew it's there, and 
tan check with CTRL-A) . 



MAKING THE ACTUAL COPIES 

As you have seen* you can get Into the Filer by typing F when you have 
the COHHAND prompt line on the screen- You must have diskette APPLEl: 

or diskette APPLEl?: in one of the disk drives when you type F to enter 

the Filer. If you forget (and APFLEl: is your system diskette), you 
will get the message 

m FILE APPLEl J SYSTEH. FILER. 



i_^ If this happens, Juat put APPLEIj in any drive and type F again- 

■ml H^ 



The Filer Is that portion of the system which allows you to manipulate 
Information on diskettes- One of the Filer's abillclea Is to transfer 
information from one diskette to another- To Invoke this facility^ once 
you have the FILER prompt Line on the screen, type T for Kransfer, 

This la what you gee: 
TRANSFER ? 
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Let's say that you want to make a backup copy of diskette APPLE3: , by 
copying AFPLE3: onto one of your newly formatted diskettes* Put 
APPLE3! Into any available dlak drive, and put a newly formatted 
diskette Into any other drive. If your system has only tvo drives you 
will have to remove diskette APPLEl: from drive #4: . Once the FtLEfi 
proB^jt line is Bhewlng^ APPLEl: la no longer needed until you visli to 
Quit the Filer and return to the COMMAND prcmpt line. Now, answer the 
qjeatlon by typing the name of the source diskette to be copiedi 

AJPLE3: 

When you press the RETURN key, the computer checks to gee that diskette 
APPLE3: is in one of the disk drives* If It is not, you will see the 
measage 

APFLE3: 

NO SUCH VOL ON-LINE <SOUHCE> 



m j ^ 

m ; ^ 



In that case, just put APPLE3: in a disk drive and type T for Traoefer fc 

again* If the computer eucceeda In finding APPLE3;, It aaka you the 

next obvious queetioni If you are going to transfer aoniethlng, then ^ 

TO WHERE ? 

Answer thle question by typing the name of the diskette that is to 

become an exact backup copy of APPLE3: ^ 

BLANK: 

Remember that BLANK: la the Tiame given CO all newly formatted diskettes 
by the FOIlKAXTER program. The colons { ; J that appear after the 
diskette naraes are quite significant; they indicate that the entire 
diskette is being referred to. 

After you have told the computer where you want APPLESe's informfltion 
transferred (and pressed the key marked "RETURN"), It checks to see that 
SLAWIC! is also In one of the disk drives* If It is not, you will ae* 
tbe message 

PUT W BLANK: 

TYPE <SPACE> TO CONTINUE 

In that case, put BLANK: into anj disk drive sKcepC the one contalninB 
APPLK3;, and press the Apple's spacebar* When the computer succeeds in 
finding boch the source and the destination dlakettea, it says 

TRANSFER ZS^ BLOCKS 1 (¥/NJ 



E 
E 

m 

E 



This message is majniy there to give you a chance to abandon Che ^ 
transfer if you made a typing error in the names of the source or the 

destination diskettes. The phraae "230 BLOCKS'* nteans merely "THE WHOLE ^ 

DISKJiTTE"'- In any caae, you type J5 



3| 



All the Information on diskette APPLE3i, including thi^ diskette's name, 
will be copied onto diskette BLANK.:, coizpletely overwricltig BLANK:* 
Thetefore, the eoroputer warns you that you are about to lose any 
information that might be stored on BLANK;- It says 

DESTROY BLANK: 7 

Since you want to turn BLANK: into a perfect copj? of APPLE3:, the 
answer Is 



The process is under way* It takes about two minutes to copy and check 
the entire diskette- When copying is done the screen celebrates by 
saying: 



APPLET: 



-> SLANK: 



by which cryptic remark the computer is telling you that the contents of 
APPLE3;, including the diskette's name, have been copied onto the 
diskette that used to be called BLANK:- This Is Just what you wanted. 

There are now twa diskettes with the aame naiue, both in the system at 
once. Thla is a risky gitustion, confusing both to you and to the 
computcri so be sure to remove the new copy right away. Now, using a 

fnarklng pen, write "APPLE3:" on the new diskette's label. Do not use a 
pencil or a ballpoint pen, as the pressure of writing may damage the 
diskette. It is very important to label diskettes Immediately, so you 

know what information is stored on thetn- 



DO IT AGAIN, SAM 

You flhould, at this time, make sure that you have at least one backup 
copy of each of your system diskettes: APPLEl:, APPLE2 ; , and APPLE3:. 
In each case, just place the source diskette to be copied from in one 
drive, the blank destination dleketto to be copied onto in another 
drive, and then type T to begin the Ttanafer. While you are at it, make 
a backup copy of AFFLE0; ^ too- It may come in liandyt later on. 



BEFORE you type Q to Quit the Filer and return to the COMMW^D prompt 
line, be sure to put diskette APPLEl: back Into drive #4: If you forget 

Co do thla, the coiT^uter will stop responding to its keyboard after you 
type q i even the RESET key will have no effect. You will have to turn 
the computer off, put APPLEl: In drive #4:, Kid turn the computer on 
again. 



Finally, you should Store the original diskettes (and one extra copy, 
you like to be really safe) away, in a safe place. 



if 
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USING THE SYSTEM 



A DEMONSTRATION 

kt last, a reward for all your work to thla point: you are finally ready 
to uee Che Apple Pascial eyatem to run a progtaia* DlaketEe APPLE3: 
concalns several "demonstration" programs. To eee a list of those 
prograiDB» put APPLE3: in any disk drive except &in f APPLE I ; must be In 
drive liti )» Now» enter the Filer by typing F in response to the 
COMMANt prcsnqst line- When the FILER prompt line appears on the screen, 
type L to List a diskette's directory* The Filer says: 

DLR USTING OF ? 

In respDose, type the ABine of the diskette: whose Ulrectory you wish to 
6e«t 

A long list of prograni files now appears on the acreen» many of them 
both in their ,TRXT veraloos (the form In which they are written and 
edited) and also in thelc compiled -CODE versiona (the form in which 
they can be executed)* When Che acrefin la full, the display stops and 
the Eoeasage 

TYPE <SPACE> TO CONTINUE 

appears at the top of the screen- Press the Apple'a apacebar to see the 
remaining fllea> For now, we arc IntereaCed in the file naioed 
GaAP»EHO,CODE • 

Since the aysteci diskette APPLE!: is already in disk drive #4: j you taay 
now type Q to Quit the Filer- When the COMMAND prompt Line appears, 
type X for K(ecute> The computer says 



m 
li 



m 



EXECUTE WHAT FILE? 

Answer by typing the oame of the diskette 
executed; 

.AfPLEaiGRAFDEMO 



uid file you wish to have 



Notet DO NOT type the auffix .CODE ; the syateni knows you can execute 
only a code file, so It automatically auppiies the siiffi* .CODE for youp 
in addition to any name that you type* 



E 

i! 
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When this message appears 

PRESS ANY KEY TO QUIT. 

PLEASE VAIT WHILE CREATIMG BUTTERFI,!: 

the program la running- After a short pause » the dlapLay begins* Just 
ait back and enjoy It: soon you'll be writing your own programs uaing 
these and other featyrea of Apple Pascal- When you are tired of 
watching, pireBS the apaeebar on the Apple'a keyboard to return to the 
COMMAND prompt line- You can use this sanie procedure Co run any of Che 
programs on AFPLE3: . These programs are diacussed In Appendix A. 



DO IT YOURSELF 

Now, for some mere experience at using the Apple Fascal ay stem, let's 
try writing a short program- Thla discussion will sssume that you are 
using your new copiee of Che Pascdi diafcettea- You should be using a new 
copy of APPLEl: aa your system dlskeCCe (or "boot diafcette" as it Is 
often called). This copy is not write-protected, and you have never 
used Che Editor to create any new files on it before. Put the new copy 
of APPLE I; in the boot drive, volume #4: • You should also put s copy of 
APPLE2; In any other drive (APPLE2: contains the Compiler program)* 

Hlth the COMMAND prompt line showing, type E to select the E(dlt 
option* Sooo. this toessage appears* 

>EDIT: 

NO WRKFILE IS PRESENT. FILE? ( <Rlt:p FDR NO FILE <ESC-RET> TO EXIT ) 



As usual, you imist use CTHL-A to eee the right half of the meaaage* 
Thla message gives you sotae Information and soine choices* The firat 
word, >EUIT; , tells you that you are now in the Editor* The next 
sentence, MO WORJCFILE IS PRESENT , tella you Chat you have not yet used 
Che Editor to create a "workfile'\ which la a "scratchpad" diakette copy 
of a program you are working on- If there had been a vorkfile on 
APFLEli , that file would have been read into the Editor automatically* 

Sine? there was no workflle to read in, the Editor aiaka you, FILE? If 
you now typed the name (including the drive's voloniG number or the 
diskette's nAme) of a *TEXT file stored on APPLEl: or on APPLE2:, that 
texCfile would be read Into the Editor- However,, there are no -TEXT 
fllea on APPLE!: or APPLE2: yet, and beaides« you want to write a new 
program- In parentheses, you are shown hov to say that you don't want 
Co tead In an aid file; <R£T> FOR NO FILE - This meana that. If you 
press the Apple's RETURN key, no file will be read in and you can start 
a new file of your own* That's just whac you want to do, ao press Che 
Apple's RETURN key (che test of the meBaage says If you first preas the 
ESC key and THEN press the RETORW key, you'll be sent back to the 
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COMMAND prompt Line). When you have pcEssed the REIURN key, Lhe full 
EDIT prance line appears: 

>EDITt ACBJSr CCPY D{LETS F(1RD IfHSRT ... 

The chapter called THE EDITOR In the Apple Pascal Operating System 
Reference Manual explains all of these ccponand options in detail; for 
now you will only need a few o£ them* The first one you will use Is 
I<NSRT , which selects the Editor's mode for inserting new text- Type I 
to select Insert incide, and yet another prompt line appears: 

>INSEftT: TEXT I':BS> A CHAil,<DEL> k LIME] [<ETX>ACCEPTS , <ESC>ESCAPESJ 

Aa Icing as this line is ahawlng at the top of the screen anything you 
type will be placed on the screen* juet to the left of the white square 
"cursor"* If the cursor is In the middle of a llnc» the rest of the 
line Is pushed over to make room for the new text- If you oake a 
mistake, just use the left-arrow key to backspace over the error» and 
then retype. At any timy during an insertion, If you press the Apple's 
ESC key your Insertion will be erased. At any time during an Inaertlon, 
If you press CTRL-C the Insertion will be made a permanent part of your 
file, safe from bf^lng erased by ESC or hy the left-arrow key. You can 
then type I to Fainter loaert oDde and type acre text* 

New for our program* With the IHSERT prompt line shaving, press the 
RETURN key a couple of times, to niove the cursor down, and then type 

PBORAFM DEMOi 

You can use any nacne for your program, but In chls discussion It will be 
called DEMO , Now press CTRL-C (type C while holding down the CfttL 
key)* Your insertion so far la made "pertaanenc", and the EDIT prompt 
line reappears* But , horrara 1 You made several typing errors w^ien 
typing the word PROGRAM . Since you have already pressed CTRL-C , it la 
too late to backspace over your errors and retype them* 

Fortunately, there are other ways- First, let's correct the missing G 
In PROGRAM . Using the lefc*arrow key, move the cursor left until it is 
sitting directly on the R , Then type I to reenter Insert mode* Ignore 
the fact that the remHinder of the line seems to have suddenly 
disappeared^ and type the ndaaing letter G * When you press CTRL-C to 
make this Insertion permanent , the rest of the line returns: 

PRCGRAFM DEMO; 

The letter F is certainly not needed, so move the cursor right {usln^ 

the right-arrow key) until It is sitting directly on the F . Now type P 

to aelect the Editor's U(LETE optiani When the DELETE prcmpt line 
appears J 

>DELETE: < > h340VIWC COMMAm)S> [cETX> TO DELETE, <ESC> TO ABORT 1 

press the right-arrow key once. The offending F Instantly disappears- 
In Delete mode, moving the cursor In any direction deletes text- If yoii 
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flKjve the cursor b.ck ^s^ln. the deleted text reappears- What happens 
next IS similar co Insert Dade: If you preaa the ESC key. Che deletion 
if fortottS.r^ if it had never happened. If you press CTRL-C, the 
deletion 1. ^ade a permanent p.rt of your file. To re™>ve ^at F 
ptUnently. pteaa CmL-C- The line closes In to fill the deleted 
letter's pUcei 

PROGRAM DEMO; 

^ ..^^ i-v>6L pA^1rnr*a Insert and Delete modes to wrltfi 
S^t'LVrcoJ^e r-^ -rors!''^^ typing the rest cf ^ro^.^^^Jf^ 
iTo ^ur flu! Be Lre to "accept" your insertions, from time to time, 
bv pressing CTRL-C . That way. you ffllnlmlae your loss If you 
accidentally pceas the ESC key. Here is the complete program: 

PROGRAM DEMO; 

USES TUltTLEGBAPUICS , APPLESTUFF; 
VAK ANGLE, DISTANCE : INTEGERj 

PaOCECURE CRAWL J 
BEGIN 

MOVE (2 * DISTANCE) ; 

TURN (ANGLE) 
EHDi 

BEGIN 

ANGLE :- dt 
REPEAT 

INITTURTLE; 

PENCOLOR (WHITE) j 

FOR DISTANCE :- 1 TO 99 DO CRAWL i 

AMGLE :- AMGLE + 5 
UNTIL KEYPRESS; 
TEXTMODE 

When you are typing this program, the punctuation and spelling must be 
eiaetiv as ahown. The Indentation of the 11 nee Is not Important, but it 
easier to read as shown- You will notice that, cnce you have started a 
new indentation, the Editor taalntaltis that indentation for you- ^^^^^e 
back to Che left, JiJSt press the left-arrow key before you type anything 
on the new Line- 
Program DEMO makea use of graphics routines in the Unit TURTLEGRAPHICS , 
and uses the keypress function from the Unit APPLESTUFF (see Chapter 7 
for details). The third lltie of the program declareB two integer 
variables. DISTANCE and ANGLE. Next, a Pascal procedure named LitAWU la 
defined, between Che first BEGIN and ENDj . From here on, ^^^^ time 
this new Pascal statement CRAWL is used, a graphics turtle will trace 
a line on the screen, of length 2*DISTANCE moving in the current 
direction, and will then change the direction by an amount ANGLE. 
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The next HfiGlN and the last END* outline the nialii program- The portion 
of the program from REPEAT to UNTIL KEYPRESS ia repeated over and over 

again, until any key on the Apple's keyboard la pressed- 

lo each repetition, the screen la cleared and the tracing color Is set 
to WHITE. Then the procedure CRAWt Is performed, firac irtch the value 
of DISTAWCE set to one, then with DISTANCE set to the value twp , and so 
OD, unCJl DISTANCE la set CO 59 . The "turtle" ocves, then turns, then 
movea 3DID& cBore, then turns again, and so on, for 99 steps. That 
completGa one design on the screen. In the next repetition. If no key 
has beea pressed, the ANGLE baa Increased by 5 degree:?, the screen Is 
cleared by INITTURTLE, and the whole process atarta again* 

Now you should save this program- With the EDIT protttpt line showing, 
type Q CO select the QCUlT option* The following message appears: 

>gUIT; 

IJ(PaATE THE WORKFILE AKD LEAVE 

E{XIT WITHOUT UPDATING 

R(ETURN TO THE EDITOR WITHOUT UPDATING 

HCRITE TO A FILE NAME AND RETLfRK 

Type U Co create a "workfiLe" diskette copy of your program Cfuture 
versions of this file will be "Updates)". This workflle Is a file on 
your boot diskette {APPLEU) called SYSTEM<WEK.TEXT . The computer says 

WKITINC 

YOUR. FILE IS 330 BYTE3 LUNG. 

(the number of bytes may be a llEtle dlffereflC) and then the CQMMAJiD 
prompt Une reapp^^rs. Now type R to select the El(UK Option. This 
autOhLaElcally calls the Compiler for you^ since the workflle contains 
text- The disk drive containing AFPLE2; whirrs and. If you have cyped 
Che program perfectly, the following messages (again, perhaps with 
slightly different nuinbers) appear, one by one: 

COMPILING.** 



PASCAL COMPILER II. 1 (B2B] 

< (!>.... 
lURTLEGR [ 2483 WORDSI 

< 5> ..*,...., **** 

APPLESTLf [ i^7S WORDSI 

< 30>.. 

CRAVt. [ 109B WORI^S] 

< 46> 

CEKO [ 11(J9 WORDSI 

< 51^ 

59 LINES 

SMALLEST AVAILABLE SPACE - 1098 WORDS 
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If the Coo^iler discovers mistakes, it will give you a message such as 

PROFRAM <«i 

LIME 2, ERROR 18: <SP? (CONTINUE) , <ESC>(TERMINATE) , E(DIT 

Don't despairi Jusc type E for E(DIT . Vaur workflle will be 
aucomatically read hack Into the Editor for repairs. Read the error 
DieBsage at the top of the screeui press the spacebar, and ttiake sny 
necessary changes using Knsert and DCelete* Then Q(uit, U(pdate the 
workfile, and R(un your program again, by typing Q II R (the Apple will 
store up several conmands in advance). 

When your program has been successfully Compiled, It ia automatically 
executed- You will see che Qiessage 

EUN14INC. 

and then a hortaontal line appears on the acrcen. That Is the first 
deaigrt your program draue : the white "turtle" moves out a distance 2*1 , 
turns an angle ^ i movea 2*2 , turns ; moves 2*3 , turns Ijf j etc. 
Keep watching as successive designs turn through larger and larger 
angles between ooves. When you want Co Interrupt Che program, press any 
key on the keyboard. You can R{un Che program again at any time, by 
typing R . Since the latest version of your progratn has already been 
CQinplled, it will be executed inmedifltely, this clrae. 

Try making changes to the program, by setting a different starting 
ANGLE, or a different Increment to the ANGLE, or a dlfEercnt distance to 
MOVE. To do this, type E for E(DIT, use Ifnsert and D(elete to make 
changes, and Chen Qfuit* UCpdate the workflle, and R(un again by typing 
Q U R . This cycle of Edlt-Run-EdlC-Run is the baals of all program 
development in the Apple Pascal system. 

The VDckflle on APPLEL: now contains che text version of your program in 
a file named SYSTEM*WilK.TEXT , and the compiled P-code version of your 
program In another file named SYSTEM* WKK. CODE * When your program l9 
ruQnlng as you want it to, you should save the tewt and code workfile 
under other filenames. With the COMMAND prompt line showing, type F to 
enter the Filer. When the FILER prompt line appears, place in any 
available drive the diskette on which you vant your prograin stored- 
then type S for S(ave- You will be asked 

SAVE AS ? 

and you should respond by typing the name &f the deatindtion diskette, 
followed by a cclon, followed by any filename with ten or fewer 
characters' For example, you mlgbt type 

MYDISK:DEMO 

When you press che RETURK key, Che boot diskette's workfile, 
SYSTEM. WRK. TEXT and SYSTEM. WRK*CODE, 1b saved on MYBlSK: under the 



STARTING [WO OR MORE DRIVES) 185 



filenames DEMO. TEXT and 0EMO,CODE 
has happened; 

APPLEl jSYSTEHtWRK.TEXT 
— > MYDlSK:DEMO,XBXT 

APPLEl sSYSTEM.WRit. CODE 
— > M¥DISK:DEMO*CODE 



WHAT TO LEAVE IN THE DRIVES 



These meesagfifl vlll tell you what 



When 7DU turn the Apple off, it Is a good idea to leave the diskette 
called AFPLEl: In disk drive &h: , If there Is no diskette or sons 
other dlflkette in &U: i^hen the Apple la accidentally turned on, the 
drive will apln the disk indefinitely. If thle continues for hours and 
houra, some wear will take place on the diskette and the drive. So It 
±B a good idea to make a habit of leaving a copy of APPLEl: (now that 
you have copies) jn tfA: when you turn the ay stem off. 

Of course, if you turn cm the ayatem and APPLEl: is not in P^i, just 
press the key inarked RESET - Place APPLEl: In #4: and turn the system 
of£ and then on again. No damage results from tumlnE on the computer 
with the wrong diskette (or no diskette) in the drive. Gradual, 
uQnecessary vear resulca from leaving the disk drive running for a long 
period of time with the incorrect diskette (or no diskette) in the 
drive- 



USING MORE THAN TWO DRIVES 



The primary difference between using a two-drive syateni and using larger 
eysteme is that you rarely need to remove APPLE!: froin its usual 
location in drive M: , and can do all copying and transferlng between 
files in the other drives- 

For example^ with four driveB, you can have APPLEl; In 9At , APPLE2: in 
f5:, and APPLE3t In tfll:; then you can format diskettes by placing chetn 

in ^I2i, without having to remove any of the Bystetn diskettes. 

A one-drive system le a useful tool for learning Pascal and running 
programs written on other flye terns, A one-drive ayatem can, in fact, do 

anything that the larger syetema can do, up to the limits of the actual 
storage ap.aee available. For software development of any magnitude, 
hewevEr, t«o drives are recoaiinended. Again, more drives make life 
eaelet* Word proceBslng, uaing the text editor, is most pleasant with a 
three-drive aysteoi. Some business applications, which can benefit from 
having over half a megabyte on line, might use six drives. 

No specific instructions will be given here on using nwltiple-drlve 
ByaneiESt Acquaintance with a two-drive system should be sufficient 
introduction. 
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MULTIPLE-DRIVE SUMMARY 



STARTING UP THE SYSTEM 

To start the syatem, place diskette APPLEl: in disk drive fl^4: (slot b, 
drive l)l then turn on the Apple's power- When the "WELCOME" message 
appears. Pascal is running. 



FORMATTING NEW DISKETTES 

To forTnat & new diskette, have fascal'a COMMAND prompt line shoving. 
Plate diskette APPLE3: In any drive except #A: , and type 

X 
Now, in response to the query 

EXECUTE WHAT FILE? 

type 

APPLE3:FCJilMATTER 

When the question: 

FOilMAT WHICH DISK ? 
appears, place the new diskette in any drive except ffi: , and then type 
the number of that drive* For example. If you put the new diskette in 
drive #5: , type 

5 
Wlien you press the RETURN key, the diskette will bo formatted. To leave 
the formatting program, press the RETURN key in response to the question 
WHICH DISK ? A newly formatted diskette has the name BLANK: 



COPYING DISKETTES 

To copy a diskette, have the COMMAND prompt line showing, and put 
APPLEl! in drive ffA: - Get Into the Filer by typing 

F 
Once the FILER prompt line is showing, you may remove APPLEl: from 
its drive if you need to. Put the source diskette you wish to copy 
Into one drive, and the destination diskette you want to copy onto 
into another drive, then type 

T 
Now, when this queecion appears: 

TRANSFER 1 
reply hy typing the name of the source diskette to be copied, and then 
press the RETURN key. For example^ you night type 

APPLE3 ! 
Now, when the next question appears: 

TO WHERE ? 
reply with the name of the destination diskette that I& to become the 
backup copy* For exanple, yau might type 

BLANK: 
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Lastly, yaa will be aflked 

TEtANSFEK 28(5 BLOCKS ? 
and 

DESTROY BLAMK: ? 
Reply 

Y 
to both, and BLAMK; will be turned into a perfect copy of APPLE3J » 
Be Huce to put dlgkecte APPLEls hack into drive *4: before QfulttluK 
the Flier. '^ 



EXECUTING A PROGRAM 

To execute a. prevloLialy compiled program, put WPLEl: io drJve ^4: and 
put the diskette containing the program file Into any other drive* 
With Che CO^QlAWO prompt line sbowing, type X for X(ecute* When the 
coistputer prompts 

EXECUTE WHAT FILE? 
answer by typing the name of the diskette and codefile you wish to 
have executed* DO NOT type the .CODE aufflx. For exaiuplBi to execute 
the program GRAFPEMO,CODE on diskette APPLE3: » you would type 

APPLE3:CFIAFDEM0 
The pragraiii should now run. 



WRITING A PROGRAM 



To start a new file In the Editor, put APPLEl : in drive ^4: and put 
APPLE2: in drive #5: * With the COMMANU prompt line showing, type F 
to enter the Filer, Then type N for K(gw. If you are asked 

THROW AWAY CURRENT WORitFlLE 7 
type Y for Y<es. When you see the message 

WOKKFILE CLEARED 
type 4 to <3(ulc the Filer, and then type E to enter the Editor, 
This toes 3 a ^e appears : 

>EDir: 

KO WURKFILE IS PRESENT. FILE? ( <RET> FOR NO FILE <ESC-RET> TO EXIT ) 
Presa the RETUE^ key, and the full EDITe proinpt line appears- You can 
now insert csKt at the cursor position by typing I for I (osert and 
ther typing your program* Conclude each insertion by pressing CTRL-C* 
Delete t£xt at the cursor poaltion by typing for DCelete and then 
moving the cursor to erase text. Conclude each deletion by pressing 
CTKL-C i When you have written a version of your program^ type Q to 
Qfuit the Editor, and then type U to ll(pdate the workfile to contain 
your latest program version. 

With the COMMAND protopt line showing, you can Chen type R to Rfun 
your program. This automatically compiles the text workfile (uElng 
the Compiler program on APPLE2:), stores the compiled code workfile, 
and executes lt» To reenter the Editor, type E in response to the 
COMMAND prompts The text workfile is automatically read back into the 
computer* 



lee Apr\E pascal language 



r 


« 




■ji 


i: 


S 


t- 


^ 


1 


^ 


r 


^ 


i 


^ 


m 

m 


^ 


k ' 


^ 


i ' 


i4 






3 


M-i 


^ 


Ci 


H 


m- > 


3 



When a vetaion of your program is complete, you can Dtpdare the text 
workfile to contain that litest version and R(un the program to create 
a code workfile of that versioDi To save the workfile versions of 
your program on another diskette for later use, place that diskette 
in drive #5; and type F in responae to the COMMAND prompt to enter 
the Filer. Then type S for S(ave- When you see the proBjpC 

SAVE AS ? 
type the name of the diskette and file where you want your program 
saved. Do not type any *TEXT or ,CODE suffix. For example, If you 
want your progrsn* saved under the filename OEHO on the diskette 
WYlflSK; , you might type 

MYBISR:DEMO 
The text workfile SYSTEM.WRK.TETT on APPLEl: Is saved as DIS^O-TEXT on 
MYDISK.1, and the code workfile SYSTEM. WRK., CODE is aaved as DEMO. CODE 
on MYDISK: . 
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APaE PASCAl SYNTAX 



These diagrams repreacTiC all of the syntax of Apple Pascal. However, 
they do not show che semantic rules- To understand the distinction 
becweea synt&x and semantics, consider che sentence "John Smith 1b a 
citizen of the three of clubs/' This sentence la correct synCectleaUy 
(I.e., graEimatLlcaliy) but wrong aemantlcally -- the three of tlubs ia 
not aotnetlilng one can be a citizen of. 

Similarly, the diagram for a statement shows that one kind of atatecnent 
la an Identifier optionally followed by one or dbfe expreselouB m 
parecitheSBs. The dlagraiD doea not show the semantic restriction, which 
ia that the Identifier muse be the identifier oE ^ procedure. Sonie of 
the important seiMntlc reatrictlone are given In the notes aocompanylnK 
the dlaBrams, r j b 

With thia limitation in mind, you will find that the dl^graiiifl ate useful 
as reference material. To read one of theae dlagraiB, start at the left 
and follow arrows until you come out at the right. Whenever the arrows 
branch, you can go either way. Any path that goea through from the left 
to the right defines a ayntactlcally correct Apple Pascal construction. 

Circles and ovais are used to enclose characters and words that are to 
be typed exactly aa shown i for example, the word WIL In the dlagTain for 
an unsigned constant. Boxes with square corners enclose words and 
phrases chat atand for something elsej for example, the word "letter" In 
the diagram for an identifier stands for any letter. 

The vertical arrow symbol used In these diagrams corresponds to the ""' 
character in the text of chla document and on the Apple keyboard. 

A word or phrase that you find In a square-cornered boi« la the title of 
another dlafiram; the diagratE ahowa what the word or phrase can stand for 
when tappeara in other diagrams^ (Exceptions; there are no diagram, 
for letter," "digit," and "underscore.") 



Idoncifler 



'^- N i--^^" ~[-^ 
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dlsli, 



iJJil er fii- n re 




K The letters are a,,? aod A, ,2 , 

2. The digits are 0. »g , 

3. The underscore character, _ , is not available on the 
keyboard. However some external terminals provide Ic. 
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unilanKd iDtce." 
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1. The identifier in this diagram must be the identifier of a constant. 

Z, The bottom line of the diagram represents a string constant. A 
single apostrophe cannot appear aa a ch&racter In the string constant, 
alnce this would end the constant. However, you can place two 
consecutive apoetrophea in the string constant, and the reauLt will be a 
single apostrophe in tht value of the string* For exampieJ 

WRITELN('DON"T FORGET TO BOOGIIlD 

will cause the fDllowing output: 

DON'T FORGEI TO BOOGIEI 
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The Identifier in thla diagram muBt be the Identifier of 



Blmplig type 
^^^r-W^ lit em U i .i-i ]■ 



a congtanCi 




^ 



]H^7)--0GEi^^L>^ 



1. The identifier In the top line of this diagram ntust be the identifier 
of e type* 

2- The identlfier(s) in the second line define a scalar type. They are 
being declared, bo they must be identifletfl Chat are not yet decLaired oc 
predefined. 



lypfl 
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-> 



The identifier in this dlagrani oust be the Identifier of 3 type. 
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V, ^ ^J LlL-ElLiti.^ 




;r7fi.r] — csQ-yO i iJ^t^Liiu^r] — ^{^^V^ 




1. The identlfter(s) in the tcp line are being declared, so they must be 
identifiers chat are not yet declared or predefined- 

2, The identifier between the word CASE and the colon Is the tag field. 
It Is being declaredp so It rmiat be an identltler that la not yet 

declared or predefined- 

3- The identifier between the colon and the word OF cnuat be the 
Identifier qf a type- 
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js unslRniitl 





C}r-M 







3^w7)^ 




fe j :3 

g j :^ 






va-rlabl* 



^s [sj [dttittf Icr L_ 




U If the Identifier at the top of the dlaEram Is that of an array* ttie 
expreealciii(s) In square brackets may ha used CO aubacrlpt It- The 
values of the exptesBionB(a) mist be compatible with eubacrlpt types 
declared for the array- 

2* If Che Idefitifier at the top of the diagram Is that o£ a record. It 
may be followed by a period and a second Identifier^ The second 
identifier must be the identifier of one of the fields of Che record. 

3, If the Identifier at the top of the diagram la that af a pointer, it 
may be followed by the up-arrow character* 



1. The identifier In this diagram wat be the identifier of a function- jfe 

2. The boctom portion of the diagrara (square brackets and expressions) K 
indicates the formaclon of a set- The valueB of the eKpresHlona muet be ^ 
of the same underlying type# 
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3, The Identifier Iti the thind line of the diag^^Pi (above BEGIN) imiat be 
the Identifier of a procedure. 

A* The expfesfllon In an IF, REPEAT:^ or WHILE stateinent mist have a 




1. Note dhat there is a "nuil" path through tills diagram, acroae the to 
and doUB che right-hand side without Including anything. This 
represents what happens when 3 gaperfluous semicolon occurs in a 

p rag. ram. 

2. The unsigned integer at the top of the diagram is a label, and rmf«t 
have been declared In s. LABEL declaratlDn, 






^ This diagram shows all of the foriDS a procedure declaration can take: 

>j - The normal form Includes a parameter List (which may be 

^^ null). The declaration ends with a blocks 
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The FORVARD declaracion is like Che normal £aroL >exccpt that 
the word FORWARD Is used Instead of a Moct. 

Following a FORWARI] declaration, the procedure declarAtion has 
no parameter liet and ends with a block- 



E ^ 



block 



V-E<^^^^^^^> ^ '^t^; 




m :^ 



if |gf I — t>r = ) — 1 { conacVnT"! — 1\ i V^ 



u u!.-n-.Liu.rM =(gV- ri ^;i:rn -H::(7Vx 





This is one of the fundamental structural units: it contains all the 

local data declarac:[ons (except parameters) and all the statementa for 
one program* procedure , or £unc t Ion * 
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ft i3| 
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U In an Intrinsic unit, Che constants followltig CODE and DATA, must be 
integers and ahould be carefully choseTi* 

2, The words BEGIN and END with the statemefita between them are the 
"Initialization" of the unit- 
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*^ unit 



■^ US,ZS j-y [>[ JjL-»r[f if-r 
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l' The program heading may coDtaln idGntif ler? in parentheses in 
accordance with Standard Pascal liyncax. However the Ufentlfiers are 
Ignored'. 
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'^3 2< Kote that any units deflnEid In Che program must Imnedilately follov 

the prDgrani heading. This would normally be done only for test 
^ purpa5e3# 



^ 



liarqtllattan 



<>-> 




A compilation Is eiraply aoraething that the compiler can cotnplle. Thla 
may be 3 program (which may contain units), or one or core unJta 
Separated with semicolona and endlmg with s periods 
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